Комментарии не подходят для документации, обычно они используются для выделения конкретных c аспектов, имеющих отношение только к разработчикам (а не пользователям). Для достижения своей цели вы можете использовать __doc__ строки в разных местах:
- уровень модуля
- уровень класса
- уровень функции / метода
В случае, если ваш метод _run действительно длинный, и вы чувствуете, что do c -строка слишком далеко от фактического кода, это сильный признак того, что ваша функция в любом случае слишком длинная. Для большей ясности его следует разделить на несколько более мелких функций, каждая из которых может иметь свою строку do c. Например, Руководство по стилю Google предлагает, чтобы, если функция превышает 40 строк кода, она должна быть разбита на более мелкие части.
Тогда вы можете использовать, например, Sphinx чтобы проанализировать эту документацию и преобразовать ее в формат PDF.
Вот пример настройки (с использованием Google do c style ):
# -*- coding: utf-8 -*-
"""
Small description and information.
@author: Author
Attributes:
CONSTANT_1 (int): Some description.
CONSTANT_2 (int): Some description.
"""
import numpy as np
import math
from scipy import signal
CONSTANT_1 = 5
CONSTANT_2 = 10
class Test():
"""Main class."""
def __init__(self, run_id, parameters):
"""Some stuff not too important."""
pass
def _run(self, parameters):
"""Main program returning a result object.
Uses `func1` to compute X and then `func2` to convert it to Y.
Args:
parameters (dict): Parameters for the computation
Returns:
result
"""
X = self.func1(parameters)
Y = self.func2(X)
return Y
def func1(self, p):
"""Information on this method."""
pass
def func2(self, x):
"""Information on this method."""
pass
Затем с Sphinx вы можно использовать утилиту командной строки sphinx-quickstart для настройки образца проекта. Для создания документации к скрипту вы можете использовать sphinx-apidoc. Для этого вы можете создать отдельный каталог scripts, добавить пустой файл __init__.py и поместить все свои скрипты в этот каталог. После выполнения этих шагов структура каталогов будет выглядеть следующим образом (при условии, что вы не разделили каталоги сборки и исходного кода во время sphinx-quickstart (по умолчанию)):
$ tree
.
├── _build
├── conf.py
├── index.rst
├── make.bat
├── Makefile
├── scripts
│ └── __init__.py
│ └── example.py
├── _static
└── _templates
Для работы sphinx-apidoc , вам необходимо включить расширение sphinx-autodoc. В зависимости от того, какой стиль do c вы используете, вам может также потребоваться включить соответствующее расширение. В приведенном выше примере используется стиль Google do c, который обрабатывается расширением Napoleon . Эти расширения можно включить в conf.py:
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
Затем вы можете запустить sphinx-apidoc следующим образом (-e помещает каждый модуль / скрипт на отдельную страницу, -f перезаписывает существующие do c files, -P документирует частные члены (начинающиеся с _)):
$ sphinx-apidoc -efPo api scripts/
Creating file api/scripts.rst.
Creating file api/scripts.example.rst.
Creating file api/modules.rst.
Эта команда создала необходимые инструкции для самой команды сборки. Чтобы сборка также могла импортировать и правильно документировать ваши сценарии, вам также необходимо соответствующим образом указать путь импорта. Это можно сделать, раскомментировав следующие три строки вверху в conf.py:
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
Чтобы документы ваших скриптов отображались в документации, вам необходимо связать их из основного файла index.rst. :
Welcome to ExampleProject's documentation!
==========================================
.. toctree::
:maxdepth: 2
:caption: Contents:
api/modules
В конце концов вы можете запустить команду сборки:
$ make latexpdf
Затем итоговую документацию можно будет найти по адресу _build/latex/<your-project-name>.pdf.
Это снимок экрана итоговая документация:
Note that there are various темы доступны для изменения внешнего вида вашей документации. Sphinx также поддерживает множество параметров конфигурации для настройки сборки вашей документации.