2020/06/02

Spinxでドキュメントを作成する方法

背景


開発ドキュメントを作成する際、Gitで差分管理ができ、HTML(Web経由でチーム内情報共有用)とPDF(チーム外向けアウトプット用)で出力ができるドキュメント作成ツールが必要となった。調査の結果、Sphinxが上記用途に最適だったてめ、使用方法をまとめた。

記事の目的


Sphinxでドキュメントを作成する

Sphinx


ここでは、Sphinxについて記載する。

Sphinxとは


Sphinxはオープンソースのドキュメント生成ツールである。reST(reStructuredText)と呼ばれる形式で記述したテキストファイルからHTMLやpdfなど様々な形式のドキュメントを生成できる。Pythonのドキュメントにも用いられている。

利点

  • reST(reStructuredText)と呼ばれるテキストファイルでき、差分管理が容易である
  • 章や節ごとに分かれた読みやすいHTMLが生成される
  • PDFやePubなど、様々なファイルに出力可能

Sphinxの導入



インストール

  1. Sphinxのインストール
    • aptを使用する場合(Pythonはインストールしない場合)
      1. Sphinxをインストール
      2. $sudo apt install python-sphinx
    • pipを使用する場合
      1. Python、pipのインストール
      2. pyenv等を利用し、Pythonをインストール
      3. Sphinxのインストール
      4. $pip install sphinx
  2. (オプション)PDF出力を可能にするため、Tex Liveをインストール
  3. $sudo apt install texlive-full
    ※容量が大きい(5Gbyte近い)ため注意

テンプレートのパッケージ構成


sphinx-quickstartコマンドで、sphinxのプロジェクトを生成できる
$ 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.
> Separate source and build directories (y/n) [n]: y

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.
> Name prefix for templates and static dir [_]:
# ソースと、ビルド結果のフォルダを完全に分けるかどうかを決定する。
# デフォルトはソースのフォルダ内に_buildディレクトリができる。

The project name will occur in several places in the built documentation.
> Project name: test_document # プロジェクトの名前
> Author name(s): emptyset # プロジェクトの著者
> Project release []: 1.0.0 # リリース番号

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.
> Source file suffix [.rst]: # ソースファイルの拡張子(デフォルトはrst: Rest)

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]: # トップページのファイル名(デフォルトはindex)
Indicate which of the following Sphinx extensions should be enabled:
> autodoc: automatically insert docstrings from modules (y/n) [n]: n # docstringでドキュメントが書かれているモジュールのドキュメントを自動生成する
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y # doctestを用いて、モジュールのテストを行うか設定する
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y # 他のプロジェクトへのリンクを自動生成する
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y # .. todo::などと記載すると、todo表示ができる
> coverage: checks for documentation coverage (y/n) [n]: n # ドキュメントのカバレッジ状況を自動で抽出する
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: y # LaTeX と dvipng または dvisvg を用いて数式を生成する
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y # Mathjaxを用いて数式を生成する
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: n # 設定にしたがってコンテンツ表示を切り替えられる
> viewcode: include links to the source code of documented Python objects (y/n) [n]: n # Pythonのオブジェクトを探索し、ソースコードをHTMLで出力する
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: n # GitHub Pagesで公開するために、 .nojekyll ファイルを作成する
Note: imgmath and mathjax cannot be enabled at the same time. imgmath has been deselected.

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]: y # # ビルド用のバッチファイルを作るかどうかを決定する
> Create Windows command file? (y/n) [y]: y # ビルド用のバッチファイルを作るかどうかを決定する

Creating file ./source/conf.py.
Creating file ./source/index.rst.
Creating file ./Makefile.
Creating file ./make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file ./source/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.

Sphinxでドキュメントを作成するための最小構成
$ tree
.
├── Makefile # コンパイル用のスクリプト(Linux用)
├── build # コンパイルした結果(HTML,PDF)の出力先
|  ├── html # HTMLの出力先
|  └── latex # PDFの出力先
├── make.bat # コンパイル用のスクリプト(Windows用)
└── source # ソースコード
    ├── _static # アイコン画像などのテンプレート部品保管先
    ├── _templates # テーマのテンプレート保管先
    ├── conf.py # コンパイルの設定ファイル
    ├── index.rst # トップページ
    └── pages # ページ格納
      └── page1.rst # ページ1  

HTMLファイル出力のための設定

テンプレートのpackage.jsonファイルを記載する。
  1. テーマを変更
    1. テーマを選択
    2. Sphinxには様々なレイアウトのテーマが存在する(ここを参照)
    3. テーマをインストール
    4. $pip install stanford_theme
      ここでは、stanford_themeを使用する。
    5. テーマを設定
    6. conf.pyを編集
      import stanford_theme
      # html_themaを変更
      html_theme = "stanford_theme"
      # html_theme_pathを追加
      html_theme_path = [stanford_theme.get_html_theme_path()]
  2. html形式でbuildする
  3. $ cd 
    $ sphinx-build -b html source build/html

PDFファイル出力のための設定

テンプレートのpackage.jsonファイルを記載する。
  1. pdf形式でbuildする
  2. $ cd 
    $ make latexpdf

ページを追加


ページの作成、目次に追加する方法について記載する。
  1. ページを作成
  2. page1.rst
    ###########################
    page1
    ###########################
    
    | Test page!
  3. index.rstにページを追加
  4. .. toctree::
       :maxdepth: 2
       :caption: OverView
       :numbered:
    
       /pages/page1

まとめ


  • Sphinxでドキュメントを作成する方法を調査、記載した

参考文献



変更履歴


  1. 2020/06/02: 新規作成

0 件のコメント:

コメントを投稿

MQTTの導入

背景 IoTデバイスの接続環境構築のため、MQTT(mosquitto)の導入を行った。 記事の目的 MQTT(mosquitto)をUbuntuに導入する mosquitto ここではmosquittoについて記載する。 MQTT MQTT(Message Qu...