プロジェクト

全般

プロフィール

Wiki » ソフトウェア開発環境 »

Sphinx

Sphinxとは

以前、はてな日記に書いた内容を参照
http://d.hatena.ne.jp/torutk/20110519/p1

Windows へのSphinxインストール

Sphinxは、Pythonのモジュールとして作成されているので、素のWindowsにSphinxをセットアップするには、Python、依存モジュール、Sphinxを入れていく必要があります。
それなりに手間なので、必要なものをひとまとめにしたスタンドアロンインストーラがSphinx-Users.jpで用意されていますが、2016年のSphinx 1.4版から更新がないので現在では非推奨です。
http://sphinx-users.jp/gettingstarted/install_windows_standalone.html

スタンドアロンインストール

非推奨

ダウンロードしたスタンドアロンインストーラファイルを、管理者として実行します（エクスプローラ上でファイルを右クリックして[管理者として実行]をクリック）。

  • SphinxInstaller-1.2.3.20141115-py2.7-win32.exe

インストール後、コマンドプロンプトを起動し、次のコマンドが実行できるか確認します。

C:\Users\torutk> sphinx-py

>>> ^Z

C:\Users\torutk>

個別インストール（Python 2.x系）

Python 2.x系でSphinxを使いたい場合のインストールです。Python 2.x系を使う必要がなければ、後述のPython 3.x系を参照ください。

Pythonのインストール

Sphinxは、Phyton 2.7系、3.x系に対応しています。
Pythonのダウンロードページから、2.7系の最新版のDownloadをクリックします。
https://www.python.org/downloads/

Windows用のMSI形式が32bit版、64bit版と用意されていいるので、OSの版に合わせてインストールします（64bit版OSで32bit版のPythonをインストールすることも可能ですが）。

  • インストール先は空白を含まないディレクトリにします（デフォルトは C:\Python27）。
  • インストーラのコンポーネント選択で、PATHの設定を有効にしておきます。
  • 2.7.10をインストールしたら、pipも含まれていました。

Sphinxのインストール（pip）

コマンドプロンプトを管理者権限で開きます。

C:\> pip install sphinx
  :

動作確認

D:\>sphinx-build -h
Sphinx v1.3.1
Usage: sphinx-build [options] sourcedir outdir [filenames...]
  :

rst2pdfのインストール（pip）

Sphinx文書をPDFに生成する方法の1つに、rst2pdfがあります。

C:\> pip install rst2pdf
  :

個別インストール（Python 3.x系）

Python 3.x系でSphinxを動かします。Sphinxのインストールにはpipを使い、環境設定はPython 3.3で導入された仮想環境機能を使います。
日本Sphinxユーザー会の次のページに沿ってインストールします。
http://sphinx-users.jp/gettingstarted/install_windows.html

Pythonのインストール

次のサイトからWindows用のPythonインストーラーをダウンロードします（執筆時点での最新は3.7.1）。
https://www.python.org/downloads/

python-3.7.1-amd64.exe

なお、環境変数PATHにはPythonのディレクトリを設定しないでおきます。

Python仮想環境の作成

Sphinxをインストールするディレクトリを作成します。
コマンドプロンプトを開き、まず、Pythonをインストールしたディレクトリにカレントディレクトリを移動します。

C:\> cd \Python37
C:\Python37>

次に、Sphinxを使用する仮想環境を作成します。SphinxをインストールするディレクトリをD:\work\sphinxとすると、

C:\Python37> python -m venv D:\work\sphinx

仮想環境の起動

Sphinxを使用する仮想環境を起動します。仮想環境のディレクトリをD:\work\sphinxとすると、

C:\> D:\work\sphinx\Scripts\activate

(sphinx) C:\> d:
(sphinx) D:\> cd work\mydoc
(sphinx) D:\work\mydoc>

Sphinxのインストール（pip）

(sphinx) D:\work\mydoc> pip install sphinx Pillow

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インストール

restructure形式

書き方メモ

見出し

出典

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

箇条書き

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

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

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

10ヶ月前に更新