Python doctests / sphinx: руководство по стилю, как их использовать и иметь читаемый код?

Question

Я люблю doctests, это единственная тестовая фреймворк, которую я использую, потому что она написана очень быстро, а благодаря использованию со sphinx она делает такие великолепные документы практически без усилий ...

Однако, очень часто я в конечном итоге делаю что-то вроде этого:

"""
Descriptions
=============

bla bla bla ...

    >>> test
    1
bla bla bla + tests tests tests * 200 lines = poor readability of the actual code
"""

Я имею в виду, что все мои тесты с пояснениями к документации помещены в верхней части модуля, поэтому вам приходится тупо прокручивать, чтобы найти реальный код, а это довольно уродливо (по моему мнению). Тем не менее, я думаю, что doctests должна оставаться в модуле, потому что вы должны быть в состоянии прочитать их во время чтения исходного кода. Итак, вот мой вопрос: любители sphinx / doctests, как вы организуете свои doctests, например, читаемость кода не страдает? Есть ли руководство по стилю для doctests, для sphinx? Для документирования со сфинксом вы используете руководство по стилю Google или sphinx или что-то еще?

Answer 1

Я думаю, что есть два вида doctest.

1. Вы можете поместить что-то в строку документации для функции, но если это так, сделайте это коротким и простым.
2. Другой вариант - полная документация / учебник, и я делаю это отдельным файлом.

В отличие от обычной документации, красота документирования заключается в том, что вы можете быть уверены, что они будут синхронизированы с кодом, даже если они не на одном экране. При чтении кода вы хотите увидеть код, возможно, с небольшим описательным текстом. При чтении учебника вы не хотите видеть код только в примерах.