Merge pull request #853 from ix5/docs-testing-and-docs

 docs: contrib: More links, explain building the docs, syntax

docs/docs/contributing/documentation.rst

@@ -1,19 +1,6 @@
 Writing Documentation
 =====================
 
-Syntax standards
-----------------
-
-- Use ``(.venv) $ python [cmd]`` for things that need to be run inside a
-  virtual environment and be consistent, see
-  `Sphinx: Narrative Documentation`__
-- Admonitions should only be: ``note``, ``tip``, ``warning``, ``attention``,
-  (maybe also ``error``?). See `docutils: Admonitions`__.
-
-.. __: https://www.sphinx-doc.org/en/master/tutorial/narrative-documentation.html
-.. __: https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions
-
-
 .. attention::
 
    This section of the Isso documentation is incomplete. Please help by expanding it.
@@ -25,14 +12,148 @@ Syntax standards
 
    **What's missing?**
 
-   - How to run Sphinx
+   - How to install & run Sphinx (note that latest sphinx from pip is needed by theme)
    - How Sphinx works, what its philosphy is
    - Small reST intro, also link to the
      `reStructuredText Primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
    - 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.
 
+Introduction
+------------
+
+The documentation for Isso is written using the `Sphinx`__ documentation
+project in a markup language called ``reStructuredText`` (``reST``). The
+documentation files have have ``.rst`` as a file extension.
+
+``reST`` works a bit like Markdown, but has some differences. Here's an
+example:
+
+.. code-block:: rst
+
+    One asterisk: *text* for emphasis (italics),
+    Two asterisks: **text** for strong emphasis (boldface), and
+    Backquotes: ``text`` for code samples.
+
+.. __: https://www.sphinx-doc.org/en/master/
+
+Building the docs
+-----------------
+
+You will need to have the latest version of the ``Sphinx`` documentation generator installed
+`from PyPi <https://pypi.org/project/Sphinx/>`_.
+
+.. warning:: 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 version 4.5.0.
+
+Install via pip:
+
+.. code-block:: bash
+
+   $ virtualenv .venv && $ source .venv/bin/activate
+   (.venv) $ pip install sphinx
+   (.venv) $ sphinx-build --version
+   ~> sphinx-build 4.5.0
+
+Build the docs:
+
+.. code-block:: bash
+
+   (.venv) $ make site
+
+The stylesheets of the theme are written in a CSS-like language called
+`sass <https://sass-lang.com/guide>`_ 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
+``docs/_static/css/site.css``:
+
+.. code-block:: bash
+
+   apt install sassc
+   make css
+
+.. __: https://github.com/sass/sassc
+
+How to write reST
+-----------------
+First and foremost, see the
+`reStructuredText Primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
+
+**Links:**
+
+.. code-block:: rst
+
+    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/
+
+**Referencing other sections:** (see `:ref:`__)
+
+.. code-block:: rst
+
+    .. _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`.
+
+.. __: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role
+
+**Referencing other documents:** (see `:doc:`__)
+
+.. code-block:: rst
+
+    See also :doc:`/contributing` or :doc:`the news page </news>`
+
+.. __: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-documents
+
+**Code blocks:**
+
+Use ``.. code-block:: <language>`` and indent the code by one level:
+
+.. code-block:: rst
+
+   .. code-block:: bash
+
+        sudo apt install python3 python3-pip python3-virtualenv
+        virtualenv .venv
+        source .venv/bin/activate
+        (.venv) $ python [cmd]
+
+Syntax standards
+----------------
+
+- Use at most three levels of headlines:
+  ``===`` for page title, ``---`` for section headings (h3), ``^^^`` for
+  sub-headings (h4).
+- Use ``(.venv) $ python [cmd]`` for things that need to be run inside a
+  virtual environment and be consistent
+  (see `Sphinx: Narrative Documentation`__)
+- Admonitions should only be: ``note``, ``tip``, ``warning``, ``attention``,
+  (maybe also ``error``?). See `docutils: Admonitions`__.
+
+.. __: https://www.sphinx-doc.org/en/master/tutorial/narrative-documentation.html
+.. __: https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions
+
+Inspiration
+-----------
+
+The following documentation pages should serve as good examples. They are from
+related projects that also offer commenting functionality.
+
+- `Commento Documentation <https://docs.commento.io/>`_
+- `Remark42 Documentation <https://remark42.com/docs/getting-started/installation/>`_
+- `Schnack Documentation <https://schnack.cool/>`_
+
 Help
 ----
 

docs/docs/contributing/index.rst

@@ -52,6 +52,13 @@ for pluralforms_ in the templating engine.
 .. __: https://github.com/posativ/isso/blob/master/isso/js/app/i18n/
 .. _pluralforms: http://docs.translatehouse.org/projects/localization-guide/en/latest/l10n/pluralforms.html?id=l10n/pluralforms
 
+Documentation
+-------------
+
+Documentation improvements are sorely needed. Anything that makes the
+experience for a newcomer more pleasant is always welcome.
+Please see the :doc:`documentation` page for more details.
+
 Code contributions
 ------------------
 
@@ -144,8 +151,9 @@ What is currently needed?
 - `Admin Web Interface <https://github.com/posativ/isso/issues/10>`_ –
   administration via email is cumbersome with a high amount of comments. A
   administration web interface should include the ability to:
-- Delete or activate comments matching a filter (e.g. name, email, ip address)
-- Close threads and remove threads completely
+
+  - Delete or activate comments matching a filter (e.g. name, email, ip address)
+  - Close threads and remove threads completely
 
 .. __: https://github.com/posativ/isso/labels/needs-contributor
 .. __: https://github.com/posativ/isso/labels/good-first-issue

docs/docs/technical-docs/testing.rst

@@ -1,6 +1,6 @@
-#######
-Testing
-#######
+#####################
+Development & Testing
+#####################
 
 Before submitting a change, you need to verify that it does not inadvertently
 break any existing functionality in Isso.

docs/docs/toc.rst

@@ -30,7 +30,7 @@
 
    Server <technical-docs/server.rst>
    Client <technical-docs/client.rst>
-   Testing <technical-docs/testing.rst>
+   Development & Testing <technical-docs/testing.rst>
    Testing the Client <technical-docs/testing-client.rst>
    Testing the Server <technical-docs/testing-server.rst>