Ubuntu 20.04 LTS でのクイックチュートリアルになります。
Sphinx の概要
Sphinx はドキュメント作成ツールです。
reStructuredText または Markdown で書いたドキュメントを html や pdf などで出力するツールです。
https://www.sphinx-doc.org/ja/master/index.html
reStructuredText 形式でドキュメントを作成し、Sphinx でビルドすると html ファイルが出力されます。 出力した html ファイルは 別途 Webサーバーで公開します。
1. sphinx をインストールする
pip3の場合 → Sphinx 4.2.0
sudo apt -y install python3-pip sudo pip3 install -U sphinx
(補足) ※最初に apt で入れたが、バージョンが古すぎたので pip3 に変更しました。 apt の場合 → Sphinx 1.8.5
sudo apt-get install python3-sphinx
2. 「sphinx-quickstart」スクリプトで環境を作成する
カレントディレクトリ内 に環境が展開されます。
sudo sphinx-quickstart
質問に答えれば環境が作成されます。あとから「conf.py」で変更も可能です。
以下が実行例です。
$ sudo sphinx-quickstart Welcome to the Sphinx 1.8.5 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Selected root path: . You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. (Sphinx出力のビルドディレクトリを配置するには、2つのオプションがあります。 ルートパス内でディレクトリ「_build」を使用するか、 「source」および「build」ディレクトリをルートパスと分離します。) > Separate source and build directories (y/n) [n]: (規定値は no。ビルド時にも指定可) Inside the root directory, two more directories will be created; "_templates" for custom HTML templates and "_static" for custom stylesheets and other static files. You can enter another prefix (such as ".") to replace the underscore. (ルートディレクトリ内に、さらに2つのディレクトリが作成されます。 「_templates」 カスタムHTMLテンプレートの場合、およびカスタムスタイルシートやその他の静的な場合は「_static」 ファイル。 別のプレフィックス(「。」など)を入力して、アンダースコアを置き換えることができます。) > Name prefix for templates and static dir [_]: (規定値は「_ 」アンダースコア) The project name will occur in several places in the built documentation. (プロジェクト名は、作成されたドキュメントのいくつかの場所に表示されます。) > Project name: (プロジェクト名:任意) > Author name(s): (著作権者:任意) > Project release []: (リリース内容:任意) If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language. (文書が英語以外の言語で書かれる場合、ここでは言語コードによって言語を選択できます。 その後、スフィンクスは生成されたテキストをその言語に翻訳します。) For a list of supported codes, see (サポートされているコードのリストについては、を参照してください。) http://sphinx-doc.org/config.html#confval-language. > Project language [en]: ja(既定値は「en」。日本語は「ja」) The file name suffix for source files. Commonly, this is either ".txt" or ".rst". Only files with this suffix are considered documents. (ソースファイルのファイル名拡張子。 通常、これは「.rst」または「.txt」です。 このサフィックスが付いたファイルのみがドキュメントと見なされます。) > Source file suffix [.rst]:(既定値は「.rst」) (以下、すべてEnterで飛ばしても大丈夫です。) One document is special in that it is considered the top node of the "contents tree", that is, it is the root of the hierarchical structure of the documents. Normally, this is "index", but if your "index" document is a custom template, you can also set this to another filename. > Name of your master document (without suffix) [index]: Indicate which of the following Sphinx extensions should be enabled: > autodoc: automatically insert docstrings from modules (y/n) [n]: > doctest: automatically test code snippets in doctest blocks (y/n) [n]: > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: > coverage: checks for documentation coverage (y/n) [n]: > imgmath: include math, rendered as PNG or SVG images (y/n) [n]: > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: > ifconfig: conditional inclusion of content based on config values (y/n) [n]: > viewcode: include links to the source code of documented Python objects (y/n) [n]: > githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly. > Create Makefile? (y/n) [y]: > Create Windows command file? (y/n) [y]: Creating file ./conf.py. Creating file ./index.rst. Creating file ./Makefile. Creating file ./make.bat. Finished: An initial directory structure has been created. (終了:初期ディレクトリ構造が作成されました。) You should now populate your master file ./index.rst and create other documentation source files. Use the Makefile to build the docs, like so: make builder where "builder" is one of the supported builders, e.g. html, latex or linkcheck. (あなたはマスターファイル ./index.rst やその他のドキュメントソースファイルを作成する必要があります。 次のように、Makefileを使用してドキュメントを作成します。 make builder この「builder」の部分には、サポートされているビルダーを指定します。html、latex または linkcheck。)
ls コマンドで確認すると、カレントディレクトリに以下のファイルが作成されています。
Makefile _build/ _static/ _templates/ conf.py index.rst make.bat
3. ビルドする
sphinx-quickstart
の最後に記載がありましたが、
sudo make html
とすることでビルドできます。 この場合、直下の「_build」ディレクトリ内に html ファイルが出力されます。
同じく sphinx-build
コマンドでビルドする方法もあります。
同じビルドですが sphinx-build
を使うことで細かなオプション指定が可能になります。
sudo sphinx-build ./ /var/www/html/
指定可能なオプション:https://www.sphinx-doc.org/ja/master/man/sphinx-build.html