Документирование моего кода Django

Question

Я только что начал проект с Django, и я хотел написать что-то вроде фрагмента javadoc ниже для функции Python. Я видел, что могу использовать Sphinx или reStructuredText, но это кажется излишним. Каков нормальный способ сделать это в Python?

Моя цель состоит не в создании большого pdf/html с моей документацией, а в том, чтобы моя IDE (pyCharm) показывала документы, когда я вызываю свои методы.

/** 
    * 
    * @param p1 
    * @param p2 
    * @param p3 
    * @return ... 
    */ 

Answer 1

Я использую IntellJ IDEA/PyCharm широко на Django и простых проектах Python.

Способ перехода - это, безусловно, reStructuredText и Sphinx, последний только если вы хотите сгенерировать HTML или PDF-документацию. Это также как документальная библиотека Python. Я сделал переход от epydoc к reStructuredText несколько месяцев назад из-за гораздо лучшей общей поддержки последнего.

Ваш будет выглядеть строка документации, как это:

def myfunc(p1, p2, p3): 
    """myfunc does something interesting. 

    some more detail. See :meth:`my_other_func` for more information. 

    :param p1: The first parameter. 
    :type p1: string 
    :param p2: The second parameter. 
    :param p3: The third parameter. 
    :returns: True if successful, False if not. 
    """ 

    my_code(p1) 
    more_code(p2) 
    return third_part(p1,p2,p3) 

Это все, что не отличается от старого стандарта epydoc для основных элементов. PyCharm способен анализировать эту информацию, например, используя: type: specs для завершения в теле вашей функции.

Answer 2

Как уже упоминалось в PyCharm webhelp on supported docstring formats вы будете иметь три варианта:

• RestructuredText (rst) for docutils. Вам не нужно использовать Sphinx для генерации HTML. Вы можете держать его таким же легким, как вам нравится.
• epytext формат. (см. также: epydoc fields documentation)
• простой текст. Это ничего не дает в терминах переходов параметров или возвращаемых значений. PyCharm покажет только простую строку.