Заставьте Сфинкса генерировать документацию класса RST от pydoc
Я в настоящее время перемещаю всю существующую (неполную) документацию в Сфинкса.
Проблема состоит в том, что документация использует docstrings Python (модуль записан в C, но это, вероятно, не имеет значения), и документация класса должна быть преобразована в форму, применимую для Сфинкса.
Существует sphinx.ext.autodoc, но он автоматически помещает текущие docstrings в документ. Я хочу генерировать исходный файл в (RST) на основе текущих docstrings, которые я мог затем отредактировать и улучшить вручную.
Как Вы преобразовали бы docstrings в RST для Сфинкса?
2 ответа
Автодок действительно генерирует RST, только нет официального способа получить его из него. Самый простой способ получить это - изменить метод sphinx.ext.autodoc.Documenter.add_line , чтобы он выдал мне полученную строку.
Поскольку все, что мне нужно, это однократная миграция, вывода на стандартный вывод мне достаточно:
def add_line(self, line, source, *lineno):
"""Append one line of generated reST to the output."""
print self.indent + line
self.directive.result.append(self.indent + line, source, *lineno)
Теперь autodoc печатает сгенерированный RST на стандартный вывод во время работы, и вы можете просто перенаправить или скопировать его в другое место.
Насколько мне известно, для этого не существует автоматизированных инструментов. Поэтому мой подход заключался бы в написании небольшого скрипта, который считывает соответствующие модули (на основе sphinc.ext.autodoc) и вставляет строки документации в файл (отформатированный соответствующим образом).