From: Stephen Finucane <stephen@that.guru>
Date: Fri, 9 Sep 2022 14:28:45 +0000 (+0100)
Subject: docs: Add info on contributing docs
X-Git-Tag: v3.2.0~131
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4bb96ce7c4c6e90545994f2491d84032c4eae3b6;p=thirdparty%2Fpatchwork.git

docs: Add info on contributing docs

Noticed while whipping up a patch to document the new VSCode extension.

Signed-off-by: Stephen Finucane <stephen@that.guru>
---

diff --git a/docs/development/contributing.rst b/docs/development/contributing.rst
index 16b3740d..7bf5e1ca 100644
--- a/docs/development/contributing.rst
+++ b/docs/development/contributing.rst
@@ -141,6 +141,43 @@ for more information.
     <release-notes>` using the ``api`` section.
 
 
+Documentation
+-------------
+
+All documentation files including release notes are authored in
+`reStructuredText`_ (rST). This is similar Markdown but significantly more
+powerful and with a slightly trickier syntax. `Sphinx`_ is used for building
+the documentation tree and the built documentation is published on `Read the
+Docs`_.
+
+The documentation tree is broadly broken down into five categories:
+
+`api`
+  Documentation for the APIs.
+
+`deployment`
+  Documentation for people that wish to deploy or maintain a Patchwork
+  instance.
+
+`development`
+  Documentation for people that wish to contribute to Patchwork itself.
+
+`releases`
+  Release notes.
+
+`usage`
+  Documentation for people that wish to use and interact with an existing
+  Patchwork instance.
+
+When contributing documentation, consider where your new documents should live.
+You should also ensure the documentation builds after your modifications. This
+can be done using the ``docs`` *tox* target.
+
+.. code-block:: shell
+
+   $ tox -e docs
+
+
 Reporting Issues
 ----------------
 
@@ -186,5 +223,8 @@ Further information about the Patchwork mailing list is available can be found o
 .. _reno: https://docs.openstack.org/developer/reno/
 .. _QEMU guidelines: http://wiki.qemu.org/Contribute/SubmitAPatch
 .. _Django REST Framework documentation: http://www.django-rest-framework.org/api-guide/versioning/
+.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+.. _Sphinx: https://www.sphinx-doc.org/en/master/
+.. _Read the Docs: https://readthedocs.org
 .. _GitHub issue tracker: https://github.com/getpatchwork/patchwork
 .. _lists.ozlabs.org: https://lists.ozlabs.org/listinfo/patchwork