すでに作り方についてのページが多いのでそれを組み合わせればsphinxの使い方は把握できる．下にある参考文献の上四つを読めば実装までいける．
ここでは，自分用のドキュメントを作成するための簡便な方法を紹介する．一つ一つの操作の意味に関しては他サイトを参照のこと．
コードからdocument作成までの手順
参考文献を踏まえた上で，ドキュメント作成までの手順を簡単に説明する．
projectのフォルダの下にsrcフォルダを作成し，その下部に機能を実行するコードを格納しておいた状態であるとする．
- project |- src | |- hoge1.py | |- hogeDir | | |- hoge2.py
hoge1.py
def hello(s):
'''return string adding hello.
Args:
s (str) : some text
Return:
str : s + "hello"
'''
return(s +"hello")
hoge2.py
def hello2(s,t):
'''combine s and t
Args:
s (str) : some text
t (str) : some text
Return:
str : s+ t
'''
return(s+ t)
sphinxのドキュメントを作成するために，以下のbash コードを回す．
cd [path to project] mkdir docs sphinx-quickstart docs
projectの名前と著者の名前以外は全部Enterの連打でok.
これでsphinxの環境が作られる．
次にconf.pyを変更する．
docs/conf.py のコードで以下の三箇所を変更する．
sphinxが読み込むpathの位置の変更．
# originally this part is commented out.
import os
import sys
sys.path.insert(0, os.path.abspath('../src'))
sphinxのextensionsの導入．
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon' ]
sphinxのテーマの変更．
html_theme = 'sphinx_rtd_theme'
今回は，hoge1用のドキュメントのページとhoge2用のドキュメントのページを分けて作成する．
以下のようにindex.rstを設定する．
toctreeのもとでドキュメンテーションへのリンクを貼る方法と，明示的にリンクを貼る2つの方法でhoge2のドキュメントにアクセスできるようにしている．
＊toctreeの下に，.rstのファイル名を書くと左側のcontent部分にリンクが追加されていく．
.. hoge project documentation master file, created by sphinx-quickstart on Tue Oct 29 18:28:47 2019. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to hoge project's documentation! ======================================== .. toctree:: :maxdepth: 2 :caption: Contents: hogeRst Hoge1 Documentation! ===================== .. automodule:: hoge1 :members: * :doc:`hogeRst` Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`
追加で hogeRst.rstを以下のように書いておく．
Hoge2 document page ====================== .. automodule:: hogeDir.hoge2 :members:
ここまでの設定が終わったら，bashで以下のコードを打つ．
cd docs make html
これで，コードに書かれているGoogle styleのドキュメントの説明を自動的に読み取ってドキュメントを作成してくれる．
Google style, Numpy styleに関しては次のサイトを参照のこと．
Napoleon – Marching toward legible docstrings
———-雑感(｀・ω・´)————
サーバーでの公開の仕方，プログラムの回し方分かったら更新するかも．
参考文献
・Sphinxの使い方．docstringを読み込んで仕様書を生成，https://qiita.com/futakuchi0117/items/4d3997c1ca1323259844
・sphinxでpythonのクラスや関数のドキュメントを自動生成する, https://joppot.info/2018/03/30/4156
・A Simple Tutorial on How to document your Python Project using Sphinx and Rinohtype，https://medium.com/@richdayandnight/a-simple-tutorial-on-how-to-document-your-python-project-using-sphinx-and-rinohtype-177c22a15b5b
・SphinxとGitHub Pagesで技術ノートを公開しよう！，https://qiita.com/tutuz/items/88a32d94d700b33dc3ea
・見通しの良い開発ドキュメントを。自動生成ツールまとめ, https://blog.htmlhifive.com/2015/07/31/documentation-generator/
・Sphinx-Users.jp プロジェクトを作る。，https://sphinx-users.jp/gettingstarted/make_project.html
・Google Python Style Guide, http://google.github.io/styleguide/pyguide.html
・Napoleon – Marching toward legible docstrings，https://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html#
・Sphinxを使用しているサイト，https://sphinx-users.jp/example.html
コメント