Программа командной строки Python: создание man-страницы из существующей документации и включение в дистрибутив

В соответствии с общепринятой практикой у меня есть пакет Python, который включает несколько модулей и исполняемый файл script в отдельном каталоге scripts, как можно видеть .

Документация для script, помимо автоматической сгенерированной справки, предоставленной optparse, вместе с документацией пакета в подкаталоге Sphinx. Я пытаюсь:

сформировать справочную страницу для script из существующей документации
включить справочную страницу в дистрибутиве

Я могу легко сделать # 1 с Sphinx, настройкой man_pages и sphinx-build -b man. Поэтому я могу вызвать python setup.py build_sphinx -b man и создать справочную страницу в каталоге build/sphinx/man.

Теперь я хотел бы иметь созданную man-страницу, включенную в дистрибутив tarball, поэтому разработчики GNU/Linux могут найти ее и установить в нужное место. Различные параметры, такие как package_data, похоже, не работают здесь, потому что справочная страница не существует до тех пор, пока она не будет сгенерирована Sphinx. Это также может относиться к файлам i18n (.mo vs .po).

Включение файлов, которые не являются частью источника в MANIFEST.in, кажется неправильным. Возможность отправки сгенерированных файлов в исходный репозиторий выглядит ужасно, и я хотел бы избежать этого.

Должен быть один - и желательно только один - простой способ сделать это.

Ответ 1

Чтобы добавить статические man-страницы в дистрибутив, вы можете добавить их в файл MANIFEST.

recursive-include docs *.txt
recursive-include po *.po
recursive-include sample_data *
recursive-include data *.desktop *.svg *.png
include COPYING.txt
include README.txt
recursive-include man_pages

Где man_pages - каталог, содержащий копии сгенерированных справочных страниц.

Смотрите также: http://linuxmanpages.com/man1/man.1.php

Ответ 2

Я бы заставил setup.py генерировать man-страницы, вероятно, до вызова distutils.core.setup. Помните, что setup.py на одном уровне - это код python. Вы хотите протестировать и убедиться, что он работает, даже если сфинкс не установлен (если вам не нужен сфинкс). Итак, если страницы-участники уже существуют, а сфинкс недоступен, не терпите неудачу. Таким образом, кто-то, кто распаковывает исходный дистрибутив без sphinx, все равно может запустить setup.py build и другие цели.

Другой вариант - проверить man-страницы, но, как и вы, я нахожу это уродливым.

Ответ 3

То, что я видел ранее, заключается в том, чтобы предоставить цель сборки для ваших документов и очистить в файле README, что документация содержит man-страницы и может быть создана путем запуска этой цели сборки. Составители пакетов затем создают ваши документы и упаковывают их во время процесса создания пакета.

Например, fedora 18 об/мин для hawkey. Я также видел, что другие rpms следуют за моделью строительной документации одновременно с созданием источника, а затем ее упаковкой.

Ответ 4

Этот вопрос заслуживает лучшего ответа, и не только потому, что этот вопрос беспокоит меня какое-то время. Итак, вот моя реализация.

Загрузите build_manpage.py из моего проекта github (здесь ссылка на build_manpage)

Сохраните его где-нибудь, вы можете импортировать его на свой setup.py

# inside setup.py
from setuptools import setup
from build_manpage import BuildManPage

...
...

setup(
...
...
cmdclass={
'build_manpage': BuildManPage,
)

Теперь вы можете вызвать setup.py следующим образом:

$ python setup.py build_manpage --output=prog.1 --parser=yourmodule:argparser