sphinx usages

https://brendanhasz.github.io/2019/01/05/sphinx.html#file-hierarchy

sphinx可以從python文件中自動提取docstring生成文件。

docstring包括函式和類的註釋。

理解：

sphinx在手動維護的獨立文件，非程式碼文件之外， 程式碼中的註釋也可以被整合到軟體文件中。

這是sphinx強大的能力， 也踐行了程式碼即文件的理念， 確保程式碼和文件具有一致性。

在此工具之前，往往描述程式碼的文件是獨立於程式碼的另一份文件。

The autodoc extension for sphinx can automatically generate API reference doc pages from the docstrings in your python code. Python

docstrings are string literals which occur immediately after function or class definitions. They’re treated as comments, and it’s customary to document a function or class in its docstring. The autodoc extension allows you to include reStructuredText in your docstrings, and will build an API reference automatically for your module from the docstrings, while allowing for further customization.

在rst檔案中，可以通過 automodule指令來提取文件註釋。

Automodule and autoclass

After enabling autodoc, in the documentation’s .rst files, you can use the automodule directive:

.. automodule:: package_name.module
   :members:

which will insert an automatically generated API reference for the entire module. The :members:

role makes autodoc generate documentation for each member (function, class, or constant) in that module, and for each member of each class (attributes and methods).

To insert an automatically-generated API reference only for one specific class, you can use the autoclass directive:

.. autoclass:: package_name.module.class_name
   :members:
   :inherited-members:
   :exclude-members: members, to, exclude

which lists all attributes and methods, except those in the exclude-members list.

The :inherited-members: role causes members which are inherited to also be included in the documentation (this role can also be used with automodule).

Speaking of inheritance, to show a list of classes the current class inherits from , add the :show-inheritance: role to the directive.

To include only specific members, instead of specifying :exclude-members:, you can add a list of members you do want to include after :members:, eg: :members: members, to, include.

Docstring Conventions

https://www.python.org/dev/peps/pep-0257/

統一的規定提供軟體工程的靈魂， 可維護性， 清晰性， 一致性。

Rationale

The aim of this PEP is to standardize the high-level structure of docstrings: what they should contain, and how to say it (without touching on any markup syntax within docstrings). The PEP contains conventions, not laws or syntax.

"A universal convention supplies all of maintainability, clarity, consistency, and a foundation for good programming habits too. What it doesn't do is insist that you follow it against your will. That's Python!"

—Tim Peters on comp.lang.python, 2001-06-16

docstring是字元文字， 出現在 模組、函式、類、方法的定義之後。

載入後被儲存在 __doc__ 屬性中。

What is a Docstring?

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.

All modules should normally have docstrings, and all functions and classes exported by a module should also have docstrings. Public methods (including the __init__ constructor) should also have docstrings. A package may be documented in the module docstring of the __init__.py file in the package directory.

String literals occurring elsewhere in Python code may also act as documentation. They are not recognized by the Python bytecode compiler and are not accessible as runtime object attributes (i.e. not assigned to __doc__), but two types of extra docstrings may be extracted by software tools:

1. String literals occurring immediately after a simple assignment at the top level of a module, class, or __init__ method are called "attribute docstrings".
2. String literals occurring immediately after another docstring are called "additional docstrings".

單行docstring

def kos_root():
    """Return the pathname of the KOS root directory."""
    global _kos_root
    if _kos_root: return _kos_root

多行docstring

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero

與#差別

#註釋不載入到記憶體。