Notes

nbsphinx

• See sphinx tutorial new, old & nbsphinx doc

• 建一個 folder docs

• 進到 docs 裡 sphinx-quickstart 開啟 wizard

  • [] 裡的是預設值

  • release 隨便打，例如 0.1

• 跑完會出現 docs/source/conf.py，把 'nbsphinx' 加到 extensions 裡

• 在 docs 裡 make html，生成的 index.html 在 docs/build/html 裡

• 在 docs/source/index.rst 裡的 toctree 很重要不能 delete 不然 sphinx 會沒辦法 make

  • 可以自己手動改的 index.rst 的 title

• 在 docs/source 裡新增 ipynb，在 index.rst 的 toctree 裡紀錄 ipynb 的檔名（不需要副檔名）

  • 每個 ipynb file 一定要有 title

  • toctree 要對齊像這樣：

    .. toctree::
       :maxdepth: 2
       :caption: Contents:
                            <---- 這裡一定要有一個空行
       MYIPYNBFILENAME
    

  • 可以加 :hidden: 然後就會只出現在網頁左邊

  • 參考 sphinx getting started guide & toctree directive

  • 也可以改 toctree maxdepth

  • 可以有多個 toctree 用不同的 captions，像 JupyterLab doc

• 切換成 3rd party readthedoc theme

  • 需要事先 pip install sphinx_rtd_theme

  • 到 conf.py import 並更換 html_theme：

    import sphinx_rtd_theme
    html_theme = 'sphinx_rtd_theme'
    

• 內容全部加完後回到 docs 裡重新 make html

• make clean 刪除所有 build 裡的內容