simple notes for creating documentations
note: my structure is usually
├── doc
│ └── sphinx
├── Makefile
├── main_project.py
├── README.md
├── requirements.txt
└── venv
├── 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
autodoc
to work we need to specify the source directory in the generated conf.py
.import os, sys
too.html
docs, we need to generate the .rst responsible for the modules.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.*.rst
s except for modules.rst
, we may remove modules.rst
if we wish, the others make the modindex
hyperlink in the index.rst
work.make html
Steps:
sudo pip install doxygen
or from the software center.Doxyfile
in the Project_dir\doc\doxygen
using doxygen -g Doxyfile
pip install sphinx
sphinx-quickstart
.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``.
Those were the most interesting parameters that needed to be configured for me
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
Use those for UML Diagrams generation, stackoverflow answer source.
EXTRACT_ALL = YES
HAVE_DOT = YES
UML_LOOK = YES
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