reference/sphinxref.txt

# Sphinx reference
Sphinx Tutorial - https://www.sphinx-doc.org/en/master/tutorial/index.html
Sphinx tutorial - https://olgarithms.github.io/sphinx-tutorial/
Documenting with Sphinx Tutorial -
https://techwritingmatters.com/documenting-with-sphinx-tutorial-intro-overview
Read the Docs - https://about.readthedocs.com/
Sphinx Themes Gallery - https://sphinx-themes.readthedocs.io/en/latest/#themes
Write the docs Sphinx themes - https://www.writethedocs.org/guide/tools/sphinx-themes/
reStructuredText Markup Specification -
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#paragraphs
Sphinx-RTD-Tutorial - https://sphinx-rtd-tutorial.readthedocs.io/en/latest/index.html

$ python -m venv .venv
$ source .venv/bin/activate
(.venv)$ pip install sphinx
(.venv)$ sphinx-build --version

# creating the documentation layout
(.venv)$ sphinx-quickstart docs
This will present to you a series of questions required to create the basic directory
and configuration layout for your project inside the docs directory. To proceed,
answer each question as follows:
    > Separate source and build directories (y/n) [n]: Write "y" (without quotes)
    > Project name: Write "project_name" (without quotes) and press Enter
    > Author name(s): Write "First_name Last_name" (without quotes) and press Enter
    > Project release []: Write "0.1" (without quotes) and press Enter
    > Project language [en]: Leave it empty (the default, English) and press Enter

After the last question, you will see the new docs directory with the following
content.

    docs
    |____ build
    |____ make.bat
    |____ Makefile
    |____ source
        |____ conf.py
        |____ index.rst
        |____ _static
        |____ _templates

The purpose of each of these files is:

    build/
        An empty directory (for now) that will hold the rendered documentation.

    make.bat and Makefile
        Convenience scripts to simplify some common Sphinx operations, such as
        rendering the content.

    source/conf.py
        A Python script holding the configuration of the Sphinx project. It contains
        the project name and release you specified to sphinx-quickstart, as well as
        some extra configuration keys.

    source/index.rst
        The root document of the project, which serves as welcome page and contains
        the root of the "table of contents tree" (or toctree).

Thanks to this bootstrapping step, you already have everything needed to render
the documentation as HTML for the first time. To do that, run this command:

(.venv)$ sphinx-build -M html docs/sources/ docs/build/

And finally, open docs/build/html/index.html in your browser.


# C autodoc extension for sphinx
(.venv)$ pip install sphinx-c-autodoc
(.venv)$ pip install libclang

edit docs/source/conf.py:
extensions = [
    "sphinx_c_autodoc",
    "sphinx_c_autodoc.viewcode",
]

c_autodoc_roots = ["../../src/fd1d"]

edit docs/source/examples.rst:
Examples
========

.. autocfunction:: sources.c::pulse
.. autocfunction:: sources.c::sinusoidal

Reference:
https://sphinx-c-autodoc.readthedocs.io/en/latest/index.html
https://github.com/sighingnow/libclang/issues/27

# example NumPy and Google style Python docstrings
*args: variable length argument list
**kwargs: arbitrary keyword arguments
Reference:
https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html#example-numpy
https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google

# linking to a source code file
.. literalinclude:: program.py

.. literalinclude:: program.c
   :language: c
   :emphasize-lines: 12,15-18
   :linenos:

.. literalinclude:: program.py
   :encoding: latin-1

.. literalinclude:: program.py
   :pyobject: Timer.start       # start() method in the Timer class

.. literalinclude:: program.py
   :lines: 1,3,5-10,20-         # include the lines 1, 3, 5 to 10 and lines 20 till end

.. literalinclude:: program.py
   :diff: program.py.orig       # shows the diff between program.py and program.py.orig