Q&A
引用元のサイトの
> Separate source and build directories (y/n) [n]:
ソースとビルドのディレクトリを完全に分けるかどうか．
デフォルトだとソースフォルダ内に_buildディレクトリができます．
ここの部分で作成されるフォルダが変わってたんですね。
私はyを選んでいたので上記内容の構成になったようです。
前提
sphinxでpythonコードから文書を作りたい。
実現したいこと
https://qiita.com/futakuchi0117/items/4d3997c1ca1323259844
を参考にしてpythonファイルから文書を生成したいです。
試したこと
①
URLを参考に作業ディレクトリをsphinx1として、中にdocsディレクトリとmain.pyを作成しました。
その後下記を実行。
python
1$ sphinx-quickstart docs
実行後の構成は以下の通りでした。
C:. │ main.py │ └─docs │ make.bat │ Makefile │ ├─build └─source │ conf.py │ index.rst │ ├─_static └─_templates
バージョンが違うせいか、作成されたディレクトリは形式が違うようでした。
②
次にconf.pyを編集しました。
python
1# Configuration file for the Sphinx documentation builder. 2# 3# For the full list of built-in configuration values, see the documentation: 4# https://www.sphinx-doc.org/en/master/usage/configuration.html 5 6# -- Project information ----------------------------------------------------- 7# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information 8 9project = 'hoge' 10copyright = '2022, hogehoge' 11author = 'hogehoge' 12 13 14import os 15import sys 16sys.path.insert(0, os.path.abspath('../../')) 17 18# -- General configuration --------------------------------------------------- 19# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration 20 21extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon' 22] 23 24templates_path = ['_templates'] 25exclude_patterns = [] 26 27language = 'ja' 28 29# -- Options for HTML output ------------------------------------------------- 30# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output 31 32html_theme = 'sphinx_rtd_theme' 33html_static_path = ['_static'] 34
参考URLにはimport os以下3行を書き換えるよう書いてあったのですが、
何も記載がなかったためとりあえず３行分を新たに追加しました。
『conf.pyから見て１つ上のディレクトリ内のpythonファイルを読み込むため，そのpath（../）を指定します．』
今回はcon.pyはsourceディレクトリ内に入っているため、main.pyを参照するためにpathは(../../)としました。
あとはextensionsとhtml_themeをURL通りに書きかえました。
③
次にrstを編集しました。今回はmainを読み込むためmainを追加しました。
（これはmain.pyなのか後でつくるmain.rstのことなのか…）
rst
1Welcome to hoge's documentation! 2================================ 3 4.. toctree:: 5 :maxdepth: 2 6 :caption: Contents: 7 8 main 9 10Indices and tables 11================== 12 13* :ref:`genindex` 14* :ref:`modindex` 15* :ref:`search` 16
④
そしてrstファイル作成のために下記を実行しました。
C:\Users\xxxxxxx\Documents\sphinx1>sphinx-apidoc -f -o ./docs . Creating file ./docs\main.rst. Creating file ./docs\modules.rst.
実行後docsディレクトリに
main.rstとmodules.rstが作成されました。
⑤最後にrstファイルをもとにhtmlファイルを生成します。
見本は下記のようになっていました。
sphinx-build -b singlehtml ./docs ./docs/_build
ただ今回は_buildというハイフンつきのディレクトリは存在せずbuildだけだったので、
下記を実行しました。
C:\Users\xxxxxx\Documents\sphinx1>sphinx-build -b singlehtml ./docs ./docs/build Running Sphinx v5.1.1 Configuration error: config directory doesn't contain a conf.py file (C:\Users\xxxxx\Documents\sphinx1\docs)
今回はconf.pyがsource内に入っているため再度下記を実行しました。
C:\Users\xxxxxx\Documents\sphinx1>sphinx-build -b singlehtml ./docs/source ./docs/build Running Sphinx v5.1.1 loading translations [ja]... done building [mo]: targets for 0 po files that are out of date building [singlehtml]: all documents updating environment: [new config] 1 added, 0 changed, 0 removed reading sources... [100%] index C:\Users\xxxxx\Documents\sphinx1\docs\source\index.rst:9: WARNING: toctree contains reference to nonexisting document 'main' looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done assembling single document... done writing... done writing additional files... done copying static files... done copying extra files... done dumping object inventory... done build succeeded, 1 warning. The HTML page is in docs\build.
すると…index.rstにエラーメッセージが出ているみたいでmainを見つけられないと出てしまいました。
③で編集したrstの書き方が間違っているのか、main.rstを探している場所が違うのか…。
参考URLだとdocs内にindex.rstがあり、
今回作成したmain.rstも同じディレクトリ内にあるので、
main.rstとmodule.rstをsource内に移動しました。
そして再度実行。
C:\Users\xxxxxxx\Documents\sphinx1>sphinx-build -b singlehtml ./docs/source ./docs/build Running Sphinx v5.1.1 loading translations [ja]... done loading pickled environment... done building [mo]: targets for 0 po files that are out of date building [singlehtml]: all documents updating environment: 2 added, 1 changed, 0 removed reading sources... [100%] modules looking for now-outdated files... none found pickling environment... done checking consistency... C:\Users\xxxxxxx\Documents\sphinx1\docs\source\modules.rst: WARNING: document isn't included in any toctree done preparing documents... done assembling single document... main done writing... done writing additional files... done copying static files... done copying extra files... done dumping object inventory... done build succeeded, 1 warning. The HTML page is in docs\build.
一応htmlファイルが作成されたみたいです。
C:\Users\xxxxx\Documents\sphinx1\docs\source\modules.rst: WARNING: document isn't included in any toctree
上記のwarning文だけが気になっている状態です。
一応質問文を書いている途中に色々試しながらhtmlファイルまで作ることができました。
そのためあと数日でこの質問は自己解決にしようと思っています。
ここまでのやり方で何か変なやり方をしている場合はアドバイスいただけますと幸いです。
補足情報（FW/ツールのバージョンなど）
環境
Windows 10
Python 3.6.1
Sphinx 5.1.1
pip
1Sphinx==5.1.1 2sphinx-rtd-theme==1.0.0 3sphinxcontrib-applehelp==1.0.2 4sphinxcontrib-blockdiag==2.0.0 5sphinxcontrib-devhelp==1.0.2 6sphinxcontrib-htmlhelp==2.0.0 7sphinxcontrib-jsmath==1.0.1 8sphinxcontrib-qthelp==1.0.3 9sphinxcontrib-serializinghtml==1.1.5
自己解決
