Sphinx¶
- 目次
- Sphinx
Sphinxとは¶
以前、はてな日記に書いた内容を参照
http://d.hatena.ne.jp/torutk/20110519/p1
Windows へのSphinxインストール¶
Sphinxは、Pythonのモジュールとして作成されているので、WindowsにSphinxをセットアップするには、PythonおよびSphinxを入れていく必要があります。
Python インストール¶
Python 3.x系でSphinxを動かします。Sphinxのインストールにはpipを使い、環境設定はPython 3.3で導入された仮想環境機能を使います。
日本Sphinxユーザー会の次のページに沿ってインストールします。
http://sphinx-users.jp/gettingstarted/install_windows.html
次のサイトからWindows用のPythonインストーラーをダウンロードします（2024-10-20時点での最新は3.13.0）。
https://www.python.org/downloads/
| python-3.13.0-amd64.exe |
なお、環境変数PATHにはPythonのディレクトリを設定しないでおきます。
Python仮想環境の作成¶
Sphinxを使用する仮想環境を作成します。SphinxをインストールするディレクトリをD:\work\sphinxとすると、
C:\> py -m venv D:\work\sphinx
仮想環境の起動¶
Sphinxを使用する仮想環境を起動します。仮想環境のディレクトリをD:\work\sphinxとすると、
C:\> cd /d D:\work\sphinx D:\work\sphinx>Scripts\activate (sphinx) D:\work\sphinx>
Sphinxのインストール（pip）¶
(sphinx) D:\work\sphinx> pip install sphinx Pillow
rst2pdfのインストール（pip）¶
Sphinx文書をPDFに生成する方法の1つに、rst2pdfがあります。
(sphinx) D:\work\sphinx> pip install rst2pdf :
LinuxへのSphinxインストール¶
openSUSE on Windows Subsystem for Linux¶
OS標準パッケージにshpinxの有無を確認しました。
~$ zypper search sphinx Loading repository data... Reading installed packages... S | Name | Summary | Type --+-------------------------------------+------------------------------------------------------+-------- | python-Sphinx | Python documentation generator | package | python-Sphinx-doc | Documentation for python-Sphinx | package | python-Sphinx-latex | Sphinx packages for LaTeX | package | python-oslosphinx | OpenStack Sphinx | package | python-pylons_sphinx_theme | Pylons themes for python-Sphinx generated document-> | package | python-repoze.sphinx.autointerface | Sphinx extension: auto-generates API docs from Zop-> | package | python-sphinx-testing | testing utility classes and functions for Sphinx e-> | package | python-sphinx_rtd_theme | ReadTheDocs.org theme for Sphinx | package | python-sphinxcontrib-breathe | Sphinx "breathe" extension | package | python-sphinxcontrib-docbookrestapi | Extension to Sphinx for generating REST API docume-> | package | python-sphinxcontrib-httpdomain | Sphinx domain for HTTP APIs | package | python-sphinxcontrib-issuetracker | Sphinx integration with different issuetrackers | package | python-sphinxcontrib-pecanwsme | Extension to Sphinx for documenting APIs built wit-> | package | python-sphinxcontrib-programoutput | Sphinx extension to include program output | package | python3-Sphinx | Python documentation generator | package | python3-Sphinx-doc | Documentation for python3-Sphinx | package | python3-repoze.sphinx.autointerface | Sphinx extension: auto-generates API docs from Zop-> | package | python3-sphinx_rtd_theme | ReadTheDocs.org theme for Sphinx, 2013 version | package | python3-sphinxcontrib-issuetracker | Sphinx integration with different issuetrackers | package
$ sudo zypper install python-Sphinx :
work$ sphinx-quickstart :
macOSへのSphinxインストール¶
- Homebrew 参照
使い方¶
プロジェクト作成¶
対話的に作成（sphinx-quickstart）¶
空のディレクトリを作成し、そのディレクトリへ移動し、sphinx-quickstartコマンドを実行します。
work % mkdir minutes; cd minutes minutes % sphinx-quickstart Sphinx 8.2.3 クイックスタートユーティリティへようこそ。 以下の設定値を入力してください（Enter キーのみ押した場合、 かっこで囲まれた値をデフォルト値として受け入れます）。 選択されたルートパス: . Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。 ルートパス内にある "_build" ディレクトリを使うか、 ルートパス内に "source" と "build" ディレクトリを分ける方法です。 > ソースディレクトリとビルドディレクトリを分ける（y / n） [n]: :
次の項目を入力してプロジェクトを作成します。
- ソースディレクトリとビルドディレクトリを分ける（y が良い）
- プロジェクト名:
- 著者名（複数可）:
- プロジェクトのリリース:
- プロジェクトの言語
生成される構造
+- build
+- make.bat
+- Makefile
+- surce
+- _static
+- _templates
+- conf.py
+- index.rst
コマンドでバッチ的に生成（sphinx-build）¶
T.B.D.
restructure形式¶
書き方メモ¶
見出し¶
# with overline, for parts * with overline, for chapters =, for sections -, for subsections ^, for subsubsections ", for paragraphs
箇条書き¶
* レベル1の箇条書き * あいうえお * レベル２の箇条書き * は空行を入れてインデントさせる → 空行を入れて同じインデントの文を書くと、同じレベルの直前の箇条書きのレベルに揃う