Add Sphinx-based documentation

.github/workflows/pages.yaml

@@ -0,0 +1,71 @@
+---
+
+
+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.0.0
+
+      # Use micromamba instead of conda for better performance
+      - name: "Setup conda environment with micromamba"
+        uses: "mamba-org/setup-micromamba@v1"  # tested with v1.4.4
+        with:
+          environment-file: "conda-environment-dev.yml"
+
+      - name: "Install dependencies with Poetry"
+        run: "${MAMBA_EXE} run --name mxcubecore poetry install"
+
+      - name: "Build documentation with Sphinx"
+        run: "${MAMBA_EXE} run --name mxcubecore 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

conda-environment-dev.yml

@@ -3,12 +3,18 @@ channels:
   - conda-forge
 dependencies:
   - python >=3.8,<3.11
+  #
+  # Do not install *pip*!
+  # Things should be handled:
+  # - either at the *conda* level (in this file)
+  # - or at the *Poetry* level in `pyproject.toml`.
+  #- myst-parser
   - openldap
+  - poetry
+  #- pre-commit
+  #- pylint
+  #- pytest
+  #- pytest-cov
   - python-ldap=3.4.0
-  - pip
-  - pytest
-  - coverage
-  - flake8
-  - black
-  - pytest-cov
-  - pytest-mock
+  #- pytest-mock
+  #- sphinx

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
+```