В соответствии с общепринятой практикой у меня есть пакет Python, который включает несколько модулей и исполняемый файл script в отдельном каталоге scripts, как можно видеть .
Документация для script, помимо автоматической сгенерированной справки, предоставленной optparse, вместе с документацией пакета в подкаталоге Sphinx. Я пытаюсь:
Я могу легко сделать # 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, кажется неправильным. Возможность отправки сгенерированных файлов в исходный репозиторий выглядит ужасно, и я хотел бы избежать этого.
Должен быть один - и желательно только один - простой способ сделать это.
Чтобы добавить статические 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
Я бы заставил setup.py генерировать man-страницы, вероятно, до вызова distutils.core.setup. Помните, что setup.py на одном уровне - это код python. Вы хотите протестировать и убедиться, что он работает, даже если сфинкс не установлен (если вам не нужен сфинкс). Итак, если страницы-участники уже существуют, а сфинкс недоступен, не терпите неудачу. Таким образом, кто-то, кто распаковывает исходный дистрибутив без sphinx, все равно может запустить setup.py build и другие цели.
Другой вариант - проверить man-страницы, но, как и вы, я нахожу это уродливым.
То, что я видел ранее, заключается в том, чтобы предоставить цель сборки для ваших документов и очистить в файле README, что документация содержит man-страницы и может быть создана путем запуска этой цели сборки. Составители пакетов затем создают ваши документы и упаковывают их во время процесса создания пакета.
Например, fedora 18 об/мин для hawkey. Я также видел, что другие rpms следуют за моделью строительной документации одновременно с созданием источника, а затем ее упаковкой.
Этот вопрос заслуживает лучшего ответа, и не только потому, что этот вопрос беспокоит меня какое-то время. Итак, вот моя реализация.
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