The documentation for Isso has several purposes: It should help newcomers have a good experience in installing and setting up Isso, make it clear how to configure for several use cases, and invite people to improve the project by participating.
You may look at the docs/ folder to see how existing documentation is written or click the top right “Edit on GitHub” button to directly edit a page.
Sections covered in this document:
The documentation for Isso is written using the Sphinx documentation
project in a markup language called
documentation files have have
.rst as a file extension.
reST works a bit like Markdown, but has some differences. Here’s an
One asterisk: *text* for emphasis (italics), Two asterisks: **text** for strong emphasis (boldface), and Double backticks: ``text`` for code samples.
Building the docs¶
You will need to have the latest version of the
Sphinx documentation generator installed
Please avoid using the version installed by your operating system since it may be severely outdated and throw errors with Isso’s theme. Isso’s docs need at least Sphinx version 4.5.0.
Install via pip:
$ virtualenv .venv && $ source .venv/bin/activate (.venv) $ pip install sphinx (.venv) $ sphinx-build --version ~> sphinx-build 4.5.0
Build the docs:
(.venv) $ make site
You can then view the generated docs by starting a local server with
cd docs/_build/html && python -m http.server and visiting
The stylesheets of the theme are written in a CSS-like language called
sass and have the
.scss file extension.
If you have made any changes to the stylesheets, you need to install the
sassc program and then re-generate the CSS file at
$ apt install sassc $ make css
How to write reST¶
First and foremost, see the reStructuredText Primer. You can play with a live rST editor at snippets.documatt.com.
Use `Link text <https://domain.invalid/>`_ for **inline web links**. This is a paragraph that contains `a link`_ using **references**. .. _a link: https://domain.invalid/
Headings must always be underlined with at least as many characters as the text is wide.
Page title ==========
Use page title only once per file (at the top). This is also the name that the page will appear under.
Section heading (h3) --------------------
Use section heading to divide page into sections
Sub-Heading (h4) ^^^^^^^^^^^^^^^^
Use sub-heading only if necessary - if you need this many levels of headings, maybe the content chould better be spread out across multiple articles
Referencing other sections: (see :ref:)
.. _my-reference-label: Section to cross-reference -------------------------- This is the text of the section. It refers to the section itself, see :ref:`my-reference-label`.
Referencing other documents: (see :doc:)
See also :doc:`/contributing` or :doc:`the news page </news>`
.. code-block:: <language> and indent the code by one level:
.. code-block:: console $ sudo apt install python3 python3-pip python3-virtualenv $ virtualenv .venv $ source .venv/bin/activate (.venv) $ python [cmd]
Use at most three levels of headlines:
===for page title,
---for section headings (h3),
^^^for sub-headings (h4).
$ /usr/bin/commandto refer to shell commands and use
sh. For actual shell scripts, use
(.venv) $ python [cmd]for things that need to be run inside a virtual environment and be consistent (see Sphinx: Narrative Documentation)
/path/to/isso/<thing>to refer to items inside Isso’s installation directory or for user data and use
comments.dbas the name for the database,
.conf) for (user) config files.
Admonitions should only be:
attention, (maybe also
error?). See docutils: Admonitions.
Try to keep line length under 80 characters, but don’t worry when going over that limit when using links or code blocks
.. deprecated::to make it clear to readers which version of Isso are affected by an option or behavior
The following documentation pages should serve as good examples. They are from related projects that also offer commenting functionality.
Commento Documentation, especially the contributing section.
A model for good documentation has been laid out by Divio as the Divio Documentation System. It divides docs into four clear areas:
The Django docs also follow this system.
Other Tips & Tricks¶
For theme authors: Look at sphinx-rtd-theme internals
python -m sphinx.ext.intersphinx docs/_build/html/objects.inv
Also make sure you have used
correctly and not confused the two.
For easier docs development through file watching, automatic rebuilding and refreshing the browser, use sphinx-autobuild:
(.venv) $ pip install sphinx-autobuild (.venv) $ sphinx-autobuild -b dirhtml docs/ docs/_build/html
This section of the Isso documentation could be improved. Please help by expanding it.
Edit on GitHub button in the top right corner and read the
GitHub Issue named
Improve & Expand Documentation
for further information.
How to write good documentation, maybe link to a few guides and example sites
More syntax standards, and also correct wrong usage across the docs
… and other things about documentation that should be documented.