Add Sphinx-based documentation

GitHub: fix mxcube#797

.github/workflows/pages.yaml

@@ -0,0 +1,79 @@
+---
+
+
+name: "Pages"
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+on:
+  push:
+
+jobs:
+
+  "pages-build":
+
+    runs-on: "ubuntu-22.04"
+
+    steps:
+
+      - name: "Checkout"
+        uses: "actions/checkout@v4"  # tested with v4.1.0
+
+      - name: "Set up Python 3.8"
+        uses: "actions/setup-python@v4"  # tested with v4.7.0
+        with:
+          python-version: "3.8"
+
+      - name: "Install OpenLDAP's dev package with apt"
+        run: |
+          sudo apt-get update
+          sudo apt-get install --no-install-recommends --yes libldap2-dev libsasl2-dev
+
+      - name: "Install dependencies with Poetry"
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install poetry --user
+          python -m poetry install
+
+      - name: "Build documentation with Sphinx"
+        run: |
+          poetry run make --directory=./docs/ html
+
+      - name: "Upload artifact for GitHub Pages"
+        # This could potentially be run only when we intent to deploy...
+        # ...but it can be useful to have the artifact for debugging
+        # if: "github.ref_name == github.event.repository.default_branch"
+        uses: "actions/upload-pages-artifact@v2"  # tested with v2.0.0
+        with:
+          path: "docs/build/html"
+
+  "pages-deploy":
+
+    if: "github.ref_name == github.event.repository.default_branch"
+
+    environment:
+      name: "github-pages"
+      url: "${{ steps.deployment.outputs.page_url }}"
+
+    needs:
+      - "pages-build"
+
+    permissions:
+      pages: "write"
+      id-token: "write"
+
+    runs-on: "ubuntu-22.04"
+
+    steps:
+
+      - name: "Setup GitHub Pages"
+        uses: "actions/configure-pages@v3"  # tested with v3.0.6
+
+      - name: "Deploy to GitHub Pages"
+        id: "deployment"
+        uses: "actions/deploy-pages@v2"  # tested with 2.0.4
+
+
+...  # EOF

.readthedocs.yaml

@@ -1,32 +1,41 @@
+---
+
+
 # .readthedocs.yaml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
-# Required
+
 version: 2
 
-# Set the OS, Python version and other tools you might need
 build:
-  os: ubuntu-22.04
+
+  os: "ubuntu-22.04"
+
   tools:
-    python: "3.11"
-    # You can also specify other tool versions:
-    # nodejs: "19"
-    # rust: "1.64"
-    # golang: "1.19"
+    python: "3.8"
+
+  jobs:
+
+    pre_create_environment:
+      - "asdf plugin add poetry"
+      - "asdf install poetry latest"
+      - "asdf global poetry latest"
+      - "poetry config virtualenvs.create false"
+
+    post_install:
+      - "VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --only docs"
+      - "VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry env info"
+      - "echo $READTHEDOCS_VIRTUALENV_PATH"
+      - "which poetry"
+      - "which python"
+      - "which pip"
+      - "python -V"
+      - "python -m pip debug"
+      - "python -m pip list"
 
-# Build documentation in the "docs/" directory with Sphinx
 sphinx:
-   configuration: docs/conf.py
-
-# Optionally build your docs in additional formats such as PDF and ePub
-# formats:
-#    - pdf
-#    - epub
-
-# Optional but recommended, declare the Python requirements required
-# to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-# python:
-#    install:
-#    - requirements: docs/requirements.txt
+   configuration: "docs/conf.py"
+
+
+...  # EOF

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -c .
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,62 @@
+#
+
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+
+import datetime
+import importlib.metadata
+
+
+PROJECT_PACKAGE_NAME = "mxcubecore"
+PROJECT_PACKAGE_METADATA = importlib.metadata.metadata(PROJECT_PACKAGE_NAME)
+
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "MXCuBE-Core"
+author = PROJECT_PACKAGE_METADATA["Author"]
+copyright = (
+    f"{datetime.datetime.today().year}, {author}",
+)
+
+version = PROJECT_PACKAGE_METADATA["Version"]
+release = version
+
+DOCUMENT_DESCRIPTION = f"{project} documentation"
+
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "myst_parser",
+]
+
+root_doc = "contents"
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+
+html_theme_options = {
+    "description": DOCUMENT_DESCRIPTION,
+    "github_banner": "true",
+    "github_button": "true",
+    "github_repo": "mxcubecore",
+    "github_user": "mxcube",
+}
+
+
+# EOF

docs/source/contents.rst

@@ -0,0 +1,17 @@
+..
+
+
+#################
+Table of contents
+#################
+
+.. toctree::
+    :caption: Contents:
+    :glob:
+    :titlesonly:
+
+    *
+    dev/index
+
+
+..  # EOF

docs/source/dev/contributing.md

@@ -0,0 +1,4 @@
+# How to contribute?
+
+```{include} ../../../CONTRIBUTING.md
+```

docs/source/dev/index.rst

@@ -0,0 +1,17 @@
+..
+
+
+#######################
+Developer documentation
+#######################
+
+
+.. toctree::
+    :caption: Contents:
+    :glob:
+    :titlesonly:
+
+    *
+
+
+..  # EOF

docs/source/index.md

@@ -0,0 +1,2 @@
+```{include} ../../README.md
+```