Walid-Shouman
1/30/2017 - 11:04 PM

simple notes for creating documentations

simple notes for creating documentations

sphinx.md
content_copyfile_download
  • Rendered
  • Source

Sphinx considerations

note: my structure is usually

├── doc
│   └── sphinx
├── Makefile
├── main_project.py
├── README.md
├── requirements.txt
└── venv
  • sphinx-quickstart does most of the magic. Note: most of the time we'll want to add the code's documentation, thus use the autodoc option.
  • The new file structure is:
├── doc
│   └── sphinx
|       ├── build
|       ├── make.bat
|       ├── Makefile
|       └── source
|           ├── conf.py
|           ├── index.rst
|           ├── main_project.rst (will be available after the sphinx-apidoc is executed)
|           ├── _static
|           └── _templates
├── Makefile
├── main_project.py
├── README.md
├── requirements.txt
└── venv
  • For the autodoc to work we need to specify the source directory in the generated conf.py.
    ie: Uncomment and modify this line sys.path.insert(0, os.path.abspath('.')) to point to the source directory.
    In my case: It got changed to sys.path.insert(0, os.path.abspath('../..')), don't forget uncommenting the import os, sys too.
  • Before generating the html docs, we need to generate the .rst responsible for the modules.
    We use sphinx-apidoc -o source ../../ for that, where the source is where the generated .rst will be, and ../.. is the python source directory where our main_project.py exists.
  • We are interested in the generated *.rsts except for modules.rst, we may remove modules.rst if we wish, the others make the modindex hyperlink in the index.rst work.
  • Build the documentation with make html

References

setup.md
content_copyfile_download
  • Rendered
  • Source

Steps:

Doxygen

  • Install Doxygen using sudo pip install doxygen or from the software center.
  • Generate a Doxyfile in the Project_dir\doc\doxygen using doxygen -g Doxyfile
  • customize the Doxyfile as in doxygen.md

Sphinx

  • Install Sphinx using pip install sphinx
  • in Project\doc\sphinx execute the Sphinx quickstart using sphinx-quickstart.

Breathe

Read the Docs

  • (This video)[https://www.youtube.com/watch?v=oJsUvBQyHBs] illustrates how to make sphinx documentation on Read the docs and connect it with the Github repo. Plus, it explains the generated ReST format in index.rst.
meta_doc.rst
content_copyfile_download
Restructured Text Understanding
-------------------------------
Following are different ways that I used to get along with the restructured text formatting.

* Use markdown to restructured text *converter*, like `pandoc <https://pandoc.org/try/>`__.
* Use a reference `restructured text file <https://docs.python.org/2.7/whatsnew/2.7.html>`__, alongside with it's `source file <https://docs.python.org/2.7/_sources/whatsnew/2.7.txt>`__.
* Use a formal restructured text *documentation*, like `docutils <http://docutils.sourceforge.net/FAQ.html>`__

Code Block Usage Notes
----------------------
Notes: If you are looking at the source code now

::

   Using double colons, 2 newlines, and an indented block means reserve the indented block,
   to copy this block from the rawfile, don't forget un-indenting it B-)

::

  Indentation when using double colons(::) separated from it's previous line with 2 newlines
  is much more cleaner than using the :: compactly just at the end of line

Tips
----
* toctree: needs filenames after it, no need for the extension to be mentioned.
  I think it gets guessed based on the ``source_suffix`` in ``conf.py``.
doxygen.md
content_copyfile_download
  • Rendered
  • Source

Parameters

Those were the most interesting parameters that needed to be configured for me

Basic Parameters

Basic parameters that we need to configure in advance.

PROJECT_NAME           = "Our Project Name"

INPUT                  = doxygen.main \
                         doxygen.src \
                         ../../src

RECURSIVE              = YES

EXCLUDE_PATTERNS       = .git \
                         venv \
                         *.py

GENERATE_XML           = YES

UML parameters

Use those for UML Diagrams generation, stackoverflow answer source.

EXTRACT_ALL            = YES
HAVE_DOT               = YES
UML_LOOK               = YES

Organizing Doxyfile

Due to the fact that Doxyfile has many configurations, it's hard to track the parameters that were set specifically for this project.
Thus, we overwrite those parameters in a custom configuration file and include it at the end of Doxyfile.

In Doxyfile append the following

@INCLUDE               = Doxyfile.project_name

Create Doxyfile.project_name and add any parameter we want to update.
In example:

# Basic
PROJECT_NAME           = "Our Project Name"
INPUT                  = doxygen.main \
                         doxygen.src \
                         ../../src
RECURSIVE              = YES
EXCLUDE_PATTERNS       = .git \
                         venv \
                         *.py
GENERATE_XML           = YES

# UML Diagram
EXTRACT_ALL            = YES
HAVE_DOT               = YES
UML_LOOK               = YES