From 3e85c39c1c34c69dd606b0b449e9a8281b8c654b Mon Sep 17 00:00:00 2001 From: ix5 Date: Sun, 1 May 2022 13:41:01 +0200 Subject: [PATCH 1/2] [nit] docs: Rename Testing page to Development+Testing --- docs/docs/technical-docs/testing.rst | 6 +++--- docs/docs/toc.rst | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docs/technical-docs/testing.rst b/docs/docs/technical-docs/testing.rst index 432f30e62..e92065522 100644 --- a/docs/docs/technical-docs/testing.rst +++ b/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. diff --git a/docs/docs/toc.rst b/docs/docs/toc.rst index c610a20dc..5e11caea3 100644 --- a/docs/docs/toc.rst +++ b/docs/docs/toc.rst @@ -30,7 +30,7 @@ Server Client - Testing + Development & Testing Testing the Client Testing the Server From 04cca257fd248419035f1be561d135b2f850d388 Mon Sep 17 00:00:00 2001 From: ix5 Date: Sun, 1 May 2022 14:23:51 +0200 Subject: [PATCH 2/2] docs: contrib: More links, explain building the docs, syntax --- docs/docs/contributing/documentation.rst | 149 ++++++++++++++++++++--- docs/docs/contributing/index.rst | 12 +- 2 files changed, 145 insertions(+), 16 deletions(-) diff --git a/docs/docs/contributing/documentation.rst b/docs/docs/contributing/documentation.rst index aca8bdc91..9518d418b 100644 --- a/docs/docs/contributing/documentation.rst +++ b/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 `_ - 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 `_. + +.. 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 `_ 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 `_. + +**Links:** + +.. code-block:: rst + + Use `Link text `_ 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 ` + +.. __: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-documents + +**Code blocks:** + +Use ``.. code-block:: `` 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 `_ +- `Remark42 Documentation `_ +- `Schnack Documentation `_ + Help ---- diff --git a/docs/docs/contributing/index.rst b/docs/docs/contributing/index.rst index 079d0e1bb..9454dca52 100644 --- a/docs/docs/contributing/index.rst +++ b/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 `_ – 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