Pythonのコマンドラインプログラム：既存のドキュメントからマニュアルページを生成して配布に含めよう

Question

よく練習してみると、いくつかのモジュールと実行可能なスクリプトが個別のscriptsディレクトリに入っているPythonパッケージがあるhere。

optparseが提供する自動生成ヘルプとは別に、スクリプトのドキュメントは、Sphinxのサブディレクトリにあるパッケージドキュメントとともにあります。私は簡単にスフィンクス、man_pages設定で＃1を行うことができます

1. 既存のドキュメント
2. からスクリプトのmanページを生成分布に

をmanページが含まれています。私はにはしようとしていますおよびsphinx-build -b man。そこでpython setup.py build_sphinx -b manと呼んで、build/sphinx/manディレクトリにマニュアルページを生成してください。

ここで、生成されたマニュアルページを配布用tarballに含めて、GNU/Linuxのパッケージ担当者が見つけて適切な場所にインストールできるようにしたいと考えています。 package_dataのような様々なオプションは、スフィンクスが生成するまでマニュアルページがないので、ここでは動作しないようです。これはi18nファイル（.mo vs .poファイル）にも当てはまります。

ソースの一部ではないファイルをMANIFEST.inに含めても、正しく表示されません。生成されたファイルをソースリポジトリにコミットする可能性は、ひどいものです。私はそれを避けたいと思います。

これを実行するには、1つ、好ましくは1つの方法が必要です。

Answer 1

これまで私が見たことは、ドキュメントのビルドターゲットを提供し、マニュアルにマニュアルページが含まれており、ビルドターゲットを実行してビルドすることができることをREADMEファイルで明確にすることです。パッケージ管理者は、ドキュメントを作成し、パッケージ作成プロセス中にそれらをパッケージ化します。

たとえば、hawkeyのフェドーラ18 rpmは、このようにして構築されます。他のRPMも、ソースが構築されるのと同時にドキュメンテーションを構築し、それをパッケージ化するというモデルに従っているのを見てきました。

Answer 2

配布物に静的なマニュアルページを追加するには、ファイルに追加することができます。

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は、生成されたマニュアルページのコピーを含むディレクトリです。

も参照してください：私はおそらくdistutils.core.setup呼び出す前に、setup.pyは、manページを生成する原因となるhttp://linuxmanpages.com/man1/man.1.php

Answer 3

。あるレベルのsetup.pyはPythonコードであることに注意してください。スフィンクスがインストールされていなくても、（スフィンクスが必要な場合を除いて）テストを行い、動作することを確認したい。そのため、マニュアルページがすでに存在し、かつ、スフィンクスが利用できない場合、失敗しません。そうすることで、sphinxを使わずにソースディストリビューションを解凍しても、setup.pyビルドやその他のターゲットを実行することができます。

もう1つのオプションは、マニュアルページをチェックインすることですが、あなたのように、私は醜いと感じます。

Answer 4

この質問は良い答えに値する、とだけでなく、この問題はしばらくの間、私を悩ませてきたので。ここに私の実装があります。私のgithubのプロジェクトから

• ダウンロードbuild_manpage.pyそれはどこかにあなたがこのようsetup.pyを呼び出すことができます

  # inside setup.py 
  from setuptools import setup 
  from build_manpage import BuildManPage 
  
  ... 
  ... 
  
  setup(
  ... 
  ... 
  cmdclass={ 
  'build_manpage': BuildManPage, 
  ) 
  

  今

あなたのsetup.pyにインポートすることができます保存

（ここではa link to build_manpageです） ：

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