123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117 |
- # 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
|