44 lines
1.1 KiB
ReStructuredText
44 lines
1.1 KiB
ReStructuredText
Writing documentation
|
|
=====================
|
|
Documentation can be written in Markdown or reStructuredText (reST).
|
|
|
|
Use restructured text when more advanced featured are required, for example
|
|
inserting a table of contents.
|
|
|
|
Add new documentation files to ``doc/index.rst``.
|
|
|
|
|
|
Markdown
|
|
--------
|
|
Use ``.md`` file name extension.
|
|
Parsing is done with the Commonmark specification,
|
|
see https://commonmark.org/
|
|
|
|
|
|
Restructured text
|
|
-----------------
|
|
Use ``.rst`` file name extension.
|
|
For details on the syntax, see
|
|
https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
|
|
|
|
|
|
Installing documentation toolchain
|
|
----------------------------------
|
|
|
|
Install Sphinx by running this in the ``doc`` subdirectory::
|
|
|
|
doc$ sudo apt install python3-pip
|
|
doc$ pip3 install -r doc_requirements.txt
|
|
|
|
Build documentation (in the ``doc`` subdirectory)::
|
|
|
|
doc$ cmake --build ../build --target docs
|
|
doc$ make html
|
|
doc$ make pdf
|
|
|
|
Run checks::
|
|
|
|
doc$ make spelling
|
|
doc$ make linkcheck
|
|
$ codespell -I doc/codespell_ignore.txt -S "*.patch" include/ samples/pn_dev/ src/ test/
|