Sphinx¶

• 目次
• Sphinx
  • Sphinxとは
  • Windows へのSphinxインストール
    • Python インストール
    • Python仮想環境の作成
      • 仮想環境の起動
      • Sphinxのインストール（pip）
      • rst2pdfのインストール（pip）
  • LinuxへのSphinxインストール
    • openSUSE on Windows Subsystem for Linux
  • macOSへのSphinxインストール
  • restructure形式
    • 書き方メモ
      • 見出し
      • 箇条書き

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/

なお、環境変数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 参照

restructure形式¶

書き方メモ¶

見出し¶

出典

# with overline, for parts
* with overline, for chapters
=, for sections
-, for subsections
^, for subsubsections
", for paragraphs

箇条書き¶

* レベル1の箇条書き
* あいうえお

  * レベル２の箇条書き
  * は空行を入れてインデントさせる

  → 空行を入れて同じインデントの文を書くと、同じレベルの直前の箇条書きのレベルに揃う