コンテンツにスキップ

sphinx

Setup

Install

pip install sphinx

Setup repository

cd docs
sphinx-quickstart

Example

> ソースディレクトリとビルドディレクトリを分ける (y/n): y
> プロジェクト名: ProjectName
> 著者名: Author
> プロジェクトのリリース: 1.0
> プロジェクトの言語: ja

Add Python source

sphinx-apidoc -f -o ./source/[dir] ./[DIR_SRC]

下記のようにmodules.rstまでのパスをindex.rstに追記

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   ./borex/modules

docstringによる定義

Googleスタイル例
class TestClass:
    """Summary line.
    """

    def testfunc(self, x, y):
        """sum

        Args:
            x (int): 1st argument
            y (int): 2nd argument

        Returns:
            int: sum result

        Examples:
            >>> print(testfunc(2,5))
            7
        """
        return x + y

build

sphinx-apidoc -F -o ./docs/ ./
cd docs

  • html

    .\make.bat html

  • pdf

    .\make.bat latexpdf

furo

テーマカスタマイズ

conf.py
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'furo'
html_title = "BOREx"
html_static_path = ['_static']

latex_docclass = {"mydocument": "jsbook"}

GoogleStyle

Example Google Style Python Docstrings — napoleon 0.7 documentation

Google Style独自の問題あり

Reference

最終更新日: August 14, 2023
作成日: August 14, 2023