From 9a9cd0200885bbfe2e11826b3543a3d9b953960d Mon Sep 17 00:00:00 2001
From: fabcor <fabien.coronis@maxiv.lu.se>
Date: Thu, 21 Mar 2024 16:54:37 +0100
Subject: [PATCH] Add document about the documentation system

GitHub: related to https://github.com/mxcube/mxcubeweb/pull/1177
---
 docs/source/dev/docs.md | 78 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 docs/source/dev/docs.md

diff --git a/docs/source/dev/docs.md b/docs/source/dev/docs.md
new file mode 100644
index 0000000000..afde25ec6d
--- /dev/null
+++ b/docs/source/dev/docs.md
@@ -0,0 +1,78 @@
+# Working with documentation
+
+This documentation is automatically built and published from the contents of the [mxcubecore](https://github.com/mxcube/mxcubecore) repository.
+Each time the repository's `develop` branch is updated, documentation is regenerated and published to [https://mxcubecore.readthedocs.io/](https://mxcubecore.readthedocs.io/)
+
+If you want to modify this documentation, make a pull request to the repository with your suggested changes.
+
+## Modifying the documentation
+
+This documentation is built using the [Sphinx](https://www.sphinx-doc.org/) documentation generator.
+The documentation's source and configuration files are located in the `docs` folder of the [mxcubecore](https://github.com/mxcube/mxcubecore) repository.
+Sphinx will also read [Python docstrings](https://peps.python.org/pep-0257/) from the repository's source code.
+
+### Building documentation
+
+Follow the instructions for [Installing a development environment](https://mxcubeweb.readthedocs.io/en/latest/dev/environment.html).
+The development environment will include Sphinx and all necessary packages for building documentation.
+
+```{attention}
+The installation instructions linked above are written for MXCuBE-Web,
+but should mostly apply equally well for MXCuBE-Core.
+```
+
+Once you have a working environment, use these commands to build the documentation:
+
+    # goto docs folder
+    $ cd docs
+
+    # build documents with Sphinx
+    $ make html
+
+The commands above will generate documentation in `docs/html/` directory.
+The generated docs can be viewed by opening `docs/html/index.html` in your web browser.
+
+
+## More details about documentation system
+
+The documentation system is built around [Sphinx](https://www.sphinx-doc.org/).
+
+There is a `Makefile` in the `docs` directory,
+that allows building the documentation with a simple command like the following:
+
+```none
+make html
+```
+
+But the actual build is performed by the `sphinx-build` program.
+From the root of the project,
+a command like the following should build the HTML documentation:
+
+```none
+sphinx-build -M html docs/source docs/build -c docs
+```
+
+The theme used is [*furo*](https://pypi.org/project/furo/).
+
+The default markup language for Sphinx is
+[*reStructuredText*](https://docutils.sourceforge.io/rst.html).
+The [usage of *Markdown*](https://www.sphinx-doc.org/en/master/usage/markdown.html)
+to write documents is enabled via
+[*MyST*](https://myst-parser.readthedocs.io/).
+Note that for special Sphinx features such as *roles*, *directives*, and so on,
+the Sphinx documentation focuses on the Restructuredtext notation only.
+To learn how to use these features in Markdown documents,
+one should refer to the MyST documentation.
+The docstrings in Python code are still to be written with Restructuredtext syntax, though.
+
+The documentation system is configured to generate {doc}`API documentation </dev/api>`
+based on the Python code.
+The Sphinx extension used to do this is
+[*`autosummary`*](https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html).
+This extension imports (or even runs?) the code in order to do its work.
+
+The
+[*`napoleon`*](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html)
+extension is enabled to handle docstrings within the Python code
+and it is configured for
+[Google-style docstrings](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings).