Help us understand the problem. What is going on with this article?

sphinxを運用する時にハマった!まとめ

More than 1 year has passed since last update.

導入の仕方については色々ありますが、運用の仕方については資料がなかったので、本記事では運用できるまでをゴールにしています。
私の環境で発生したトラブル等については以下の通り対応していますが、本来はもっと色々な問題が出る可能性があるので、追加情報程度にとらえてください。

sphinxを運用する時にハマった!まとめ

導入自体はステキな記事がいっぱいあるので、そちらを参考にしてください。
sphinx でドキュメント作成からWeb公開までをやってみた(@kinpiraさん)

導入時のコマンドについて

色々な記事で書かれているタイミングがそれぞれに違うので、執筆時点1では以下のコマンドを使用します。

command.
sphinx-apidoc -F -o ${sphinx_source_directory} ${document_project_directory}

これで出力されるconf.pyが以下です(抜粋)

conf.py
# -*- coding: utf-8 -*-

  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, '(source directory)')


# -- Project information -----------------------------------------------------

project = '(your project)'
copyright = '(now year), Author'
author = 'Author'

# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
release = ''


# -- General configuration ---------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
]

  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'en'

  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

これでも一応は動きます。
が、運用上問題があります。

サブディレクトリ以下を見に行ってくれない

とりあえず何も考えずにmake htmlとしてみると、

make_html.warning.result
WARNING: autodoc: failed to import module '(your project)'; the following exception was raised:
No module named '(your project)'

というエラーが出つつも、build succeeded, (any) warnings. と、なんか出来たのか出来てないのか分からない状態になります。
実際はファイルとしては存在するけど、ファイルの中身に.rstで設定(自動)されている内容が表示されない、という状態です。

原因

sys.path.insert(0, '(source directory)')がコメントアウトされているためです。
(source directory)にはパッケージのルートディレクトリを指定することで解決できます。

conf.pyの設定を変更する

Shpinxでapiのドキュメント生成をする時の注意点(プログラミングの話さん)を参考に適宜設定。

  • languageは後で'ja'とかに変えておきましょう。
  • この時に作成されるindex.rstなどは英語のままです。index.rstなどを直接編集しましょう。
  • 必要であればマークダウンを採用してもいいと思いますが、今回は使わないので触っていません。

設定はちゃんと出来たのに、サブディレクトリ以下を見に行ってくれない

忘れがちですが、make htmlの前に再ビルドする必要があります。
buildしたディレクトリ以下には既にファイルがあるため、強制上書きのオプションがないとスキップされます(ログメッセージにも表示されています)

command.
sphinx-apidoc -f -o ${sphinx_source_directory} ${document_project_directory}

大事な事なんでもう一度書きますが、document_project_directoryはプロジェクトのルートです。
つまり、${document_project_directory}/(your project)がsphinxで生成したリファレンスページのトップページになります。

それでもサブディレクトリ以下を見に行ってくれない

document_project_directory以下、ネストしているディレクトリには必ずinit.pyが必要です。
これがないと当該ディレクトリ含む以下は参照されません。

とりあえず動くかどうか見たいだけならdummyでもいいですが、dummyの状態で各モジュールのページのソースが表示出来てしまうので、運用を考慮するとしっかり書いたほうがいいです。

問題が見つかり次第、随時追記していきます。

補足

sphinx-autobuildで再ビルド、ブラウザの再リロードの手間を省いてSphinx文書をサクサク作成(@mikanbakoさん)がステキすぎた。
上記問題が解決した後はsphinx-autobuildに任せて直接rstとかを書き換えてしまってもいいかもしれません。

読了後いいね!をお願いします。

どれだけの方に読んでもらっているか知りたいので、お手数をおかけしますがご協力いただけると嬉しいです。


  1. コマンド選定時の執筆時点:2018/05/24 

nomurasan
ノンプログラマーがシステムを作るには?を本気で考える元業務系Webアプリ屋系セキュリティデータサイエンティスト。 そろそろオートメーション・API(で)クリエイターになりたいおとしごろ。 https://www.slideshare.net/ssusered50fb 記事等は配属先やクライアント等の意見ではなく個人の考察によるものです。 一応念のため書いておきますが、無断での転載厳禁。
https://www.wantedly.com/users/18437113
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away