Создание справочной страницы CLI python

Я разрабатываю инструмент CLI для python (используя optparse в python2.6, но надеюсь скоро переключиться на python2.7) и я собираюсь написать справочную страницу. У меня есть некоторый опыт создания динамических страниц man:

создание выделенного метода, который содержит строку в pod format и записывает ее в файл
выполнение команды pod2man для генерации данных в формате groff для передачи команде man

Я также хотел бы создавать страницы вики с тем же содержимым, что и man-страница (с помощью pod я могу генерировать html через pod2html, и, вероятно, html можно легко перевести в формат wiki). У кого-то есть лучшая идея/поток о том, как это сделать?

Одна интересная вещь, которую я нашел в этой ссылке: Создание персональных страниц с использованием optparse и distutils

Ответ 1

Обычный способ создания документации в Python - использовать Sphinx. Например, это то, что используется в официальной документации Python. После того, как вы создали проект документации Sphinx (см. этот учебник), вы можете создавать man-страницы из файлов документации Sphinx с помощью make man. Вы также должны изменить конфигурацию в conf.py, чтобы создать соответствующий вывод.

(Стоит отметить, что хотя Sphinx является обычным инструментом для написания документации на Python, это не означает, что это обычный инструмент для создания man-страниц. Используйте то, что вы хотите!)

Ответ 2

В то время как sphinx - действительно отличная система документации, это ужасно сложно и сложно освоить. Если вам понадобится решение bang, я предлагаю вам посмотреть в моем проекте build_manpage.py.

Это не замена для надлежащего документирования ваших проектов (с помощью сфинкса или того, что когда-либо вы выбираете). Но у него есть некоторые непосредственные преимущества для программиста Python:

Вам не нужно изучать синтаксис man.
Вам не нужно изучать синтаксис rst (тем не менее, вам следует в один прекрасный день изучить его).
Вам не нужно поддерживать ваш optparser\argparser и man-страницу, сформированную во внешнем файле (в человеке, первой или любой другой системе преобразования).
Вы просто добавляете один файл в конфигурацию сборки, и для вас создается справочная страница!

Если вы хотите использовать более сложную систему, с множеством колоколов и свистов, sphinx позволяет конвертировать страницу rst с формируемой страницы в man. И недавно молодой проект использует аналогичный подход к моему парсеру и сканирует ваш ArgumentParser, чтобы создать отформатированную страницу rst, с директивами sphinx (так что вам не нужно писать ее самостоятельно. (Напротив, мой сканер создает справочную страницу напрямую).

Обратите внимание, что теперь это часть pull request для добавьте форматирование manpage в стандартную библиотеку.

Ответ 3

Я ищу аналогичный ответ. Я наткнулся на optparse/setup.py на основе решения, но, похоже, много кода для добавления. Однако в argparse будущее, может быть, argparse можно изменить, чтобы поддержать это?

Ответ 4

Если вы используете click, вы можете использовать click-man. Он может генерировать man-страницы из приложений кликов.