Хотя sphinx - действительно отличная система документирования, она ужасно сложна и сложна в освоении. Если вам нужно решение проблемы, я предлагаю вам посмотреть в моем проекте build_manpage.py .
Это , а не замена для правильного документирования ваших проектов (с помощью sphinx или любым другим способом, который вы выберете). Но у программиста на Python есть некоторые непосредственные преимущества:
- Вам не нужно изучать синтаксис
man.
- Вам не нужно изучать
rst синтаксис (тем не менее, вы должны однажды выучить его ...)
Вам не нужно поддерживать ваш optparser \ argparser и справочную страницу, отформатированную во внешнем файле (в man, rst или любой другой системе преобразования).
Вы просто добавляете один файл в свою конфигурацию сборки, и для вас создается справочная страница!
Если вы хотите использовать более сложную систему с большим количеством наворотов, sphinx позволяет конвертировать отформатированную rst страницу в справочную страницу. И недавно молодой проект, использующий аналогичный подход к моему парсеру и сканирующий вашу ArgumentParser, чтобы создать страницу в формате rst с директивами sphinx (так что вам не нужно писать ее самостоятельно.
(В отличие от этого мой сканер создает страницу руководства напрямую).
Обратите внимание, что теперь это часть запроса на получение до , добавляющего форматер man-страницы в стандартную библиотеку .