Sphinx(Python3.6)をインストールしてnginxで公開する

スポンサーリンク

Sphinxとは

Sphinxとは、ドキュメントを楽しく美しく作成できるツールです。
少し詳しく言うとreStructuredTextと呼ばれるプレーンテキストファイルをhtmlやepub形式に変換してくれるツールです。

さ*ら*クラウドや、Ansibleのドキュメントサイトは、このSphinxで書かれています!

公式ドキュメントはこちら
日本ユーザ会はこちら

reStructuredTextの記法さえ覚えてしまえばリンク貼ったり、リスト作ったり、ネットワーク図作成したりもできちゃいます!

今回は、Python3.6のインストール、Python3.6仮想環境の作成、Sphinxのインストール、buildしたドキュメントをNiginxで公開するまでを解説します!

環境

Hyper-V上のCentOS7.4
Nginxで公開する場合は、こちらを参考にNginxをインストールしておいてください!

Python3.6のインストール

Python3.6のリポジトリのインストール

# yum install -y https://centos7.iuscommunity.org/ius-release.rpm

python3.6関連のパッケージのインストール

# yum install -y  python36u python36u-pip python36u-libs python36u-devel

python3.6がインストールされたかを確認する

# ls /usr/bin | grep python
python
python-config
python2
python2-config
python2.7
python2.7-config
python3.6
python3.6-config
python3.6m
python3.6m-config
python3.6m-x86_64-config

pipとvirtualenvのインストール

# curl -kL "https://bootstrap.pypa.io/get-pip.py" |python
# pip install virtualenv

python3.6の仮想環境を作成

virtualenv <python3.6> --python=/usr/bin/python3.6
Running virtualenv with interpreter /usr/bin/python3.6
Using base prefix '/usr'
New python executable in /root/python3.6/bin/python3.6
Also creating executable in /root/python3.6/bin/python
Installing setuptools, pip, wheel...done.

※ <python3.6>は任意のディレクトリ名でも可

Sphinxのインストール

python3.6の仮想環境へ移動

# source <python3.6>/bin/activate

※ <python3.6>は、仮想環境をインストールしたディレクトリ

Sphinxのインストール

# easy_install sphinx

Sphinxがインストールされたかを確認する

# ls python3.6/bin | grep sphinx
sphinx-apidoc
sphinx-autogen
sphinx-build
sphinx-quickstart

sphinx-quickstartでプロジェクトを作成する

# mkdir <python-document> && cd <python-document>

※ <python-document>は任意のディレクトリにしてください。

# sphinx-quickstart
Welcome to the Sphinx 1.7.2 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]: → 空エンター

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 [_]:  → 空エンター

The project name will occur in several places in the built documentation.
> Project name: python-document  → 任意の名前
> Author name(s): ryonmaru  → 任意の名前
> 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
Configuration — Sphinx 3.0.0+/165897a74 documentation
> Project language [en]: → 空エンター 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]: → 空エンター 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]: → 空エンター Sphinx can also add configuration for epub output: > Do you want to use the epub builder (y/n) [n]: → 空エンター 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. 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.

Nginxのドキュメントルートにbuildしてみる

Nginxの構築はこちら

sphinx-build -b html ./ /usr/share/nginx/html/
Running Sphinx v1.7.2
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index                                                 
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                  
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

クライアントからhttps://IPアドレス/<build先のディレクトリ>にアクセスする

sphinx-setup

htmlで、ドキュメントが作成されて動作しています!

最後に

本日は、Python3.6の仮想環境にSphinxを利用して、プロジェクトの作成とビルドをしてWebサーバを利用して公開まで行いました!Sphinxのセットアップはこれで環境です。しかし、重要なのはドキュメントを作成する事です。Sphinxはドキュメントの内容を作ってくれません。ドキュメントを作成するのはあなたです! 今後は、SphinxのreST記法やフローチャート、ネットワーク図の書き方などを今後は紹介していきます。Sphinxを利用して楽しくドキュメント作成を行いましょう!

コメント

タイトルとURLをコピーしました