Все, что я хочу, - это генерировать документы API из строк документации функций в моем исходном коде , предположительно через расширение autodoc sphinx, чтобы составить мою документацию по API. Мой код следует парадигме функционального программирования, а не ООП, как показано ниже.
Я бы, вероятно, в качестве второго шага добавил бы одну или несколько страниц документации для проекта, размещая такие вещи, как вводные комментарии, примеры кода (используя doctest я полагаю) и, конечно, ссылки на саму документацию API.
Что может быть простым потоком для выполнения документации из строк документации здесь? Sphinx - очень популярный инструмент, но я нахожу его начинающим страниц немного плотным.
То, что я пробовал, из моего исходного каталога:
$ mkdir documentation
$ sphinx-apidoc -f --ext-autodoc -o documentation .
Нет сообщений об ошибках, но это не находит (или не обрабатывает) строки документации в моих исходных файлах; он просто создает первый файл для каждого источника, содержимое которого выглядит следующим образом:
tokenizer module
================
.. automodule:: tokenizer
:members:
:undoc-members:
:show-inheritance:
По сути, мои исходные файлы выглядят следующим образом, без особой церемониальной модульности или объектно-ориентированного содержимого в них (мне нравится функциональное программирование, хотя на этот раз это python). Разумеется, я усек пример исходного файла ниже, он содержит больше функций, не показанных ниже.
tokenizer.py
from hltk.util import clean, safe_get, safe_same_char
"""
Basic tokenization for text
not supported:
+ forms of pseuod elipsis (...)
support for the above should be added only as part of an automata rewrite
"""
always_swallow_separators = u" \t\n\v\f\r\u200e"
always_separators = ",!?()[]{}:;"
def is_one_of(char, chars):
'''
Returns whether the input `char` is any of the characters of the string `chars`
'''
return chars.count(char)
Или вы бы порекомендовали другой инструмент и поток для этого варианта использования?
Большое спасибо!