Fix documentation pages

.github/workflows/pages.yaml

@@ -0,0 +1,39 @@
+---
+
+
+name: "Pages"
+
+on:
+  push:
+
+concurrency:
+  group: "pages"
+  cancel-in-progres: true
+
+jobs:
+
+  "build-job":
+
+    runs-on: "ubuntu-latest"  # tested with ubuntu-22.04
+
+    steps:
+
+      - name: "Setup Python"
+        uses: "actions/setup-python@v4"  # tested with v4.7.0
+        with:
+          python-version: "3.11"
+
+      - name: "Install Poetry"
+        run: "python -m pip install poetry"  # tested with Poetry v1.5.1
+
+      - name: "Checkout"
+        uses: "actions/checkout@v4"  # tested with v4.0.0
+
+      - name: "Install dependencies with Poetry"
+        run: "poetry install"
+
+      - name: "Build documentation with Sphinx"
+        run: "poetry run make html"
+
+
+...  # EOF

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -c .
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build

docs/source/conf.py → docs/conf.py

@@ -12,18 +12,30 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
-import os
-import shlex
+import datetime
+import importlib.metadata
+
+import mxcube3
+
+
+PROJECT_PACKAGE_NAME = "mxcubeweb"  # Distribution package (not import package)
+PROJECT_PACKAGE_METADATA = importlib.metadata.metadata(PROJECT_PACKAGE_NAME)
+
+PROJECT_SLUG_NAME = PROJECT_PACKAGE_NAME
+
+# This is necessary to for the `autoflask` directive to get access to the routes
+server, _ = mxcube3.build_server_and_config(test=True, argv=[])
+# This is to avoid `Server.kill_processes`, that makes the build return non-zero
+server.flask.testing = True
+
+
+# -- Sphinx configuration -------------------------------------------------
+
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 # sys.path.insert(0, os.path.abspath('.'))
-sys.path.append(os.path.abspath("../../"))
-sys.path.append(os.path.abspath("../../mxcube3/"))
-sys.path.append(os.path.abspath("../../mxcube3/HardwareObjects"))
-sys.path.append(os.path.abspath("../../mxcube3/HardwareRepository"))
 
 # -- General configuration ------------------------------------------------
 
@@ -35,48 +47,48 @@
 # ones.
 # extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo']
 extensions = [
-    "sphinxcontrib.httpdomain",
+    "myst_parser",
     "sphinxcontrib.autohttp.flask",
-    "sphinx.ext.autodoc",
-    "sphinx.ext.doctest",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.todo",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = "index"
+root_doc = "contents"
 
 # General information about the project.
-project = u"MXCuBE3"
-copyright = u"2015, MXCuBE Collaboration"
-author = u"MXCuBE Collaboration"
+project = "MXCuBE-Web"
+author = PROJECT_PACKAGE_METADATA["Author"]
+copyright = f"{datetime.datetime.today().year}, {author}"
+
+DOCUMENT_DESCRIPTION = f"{project} documentation"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = "0.1"
+version = PROJECT_PACKAGE_METADATA["Version"]
 # The full version, including alpha/beta/rc tags.
-release = "0.1"
+release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+# language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -113,7 +125,11 @@
 # keep_warnings = False
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
+# todo_include_todos = False
+
+rst_prolog = f"""
+.. |project| replace:: {project}
+"""
 
 
 # -- Options for HTML output ----------------------------------------------
@@ -125,7 +141,13 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {}
+html_theme_options = {
+    "description": DOCUMENT_DESCRIPTION,
+    "github_banner": "true",
+    "github_button": "true",
+    "github_repo": "mxcubeweb",
+    "github_user": "mxcube",
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -149,7 +171,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -165,7 +187,13 @@
 # html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
+html_sidebars = {
+    "**": [
+        "about.html",
+        "globaltoc.html",
+        "searchbox.html",
+    ],
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -212,7 +240,7 @@
 # html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = "MXCuBE3doc"
+htmlhelp_basename = f"{PROJECT_SLUG_NAME}-doc"
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -232,10 +260,10 @@
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
     (
-        master_doc,
-        "MXCuBE3.tex",
-        u"MXCuBE3 Documentation",
-        u"MXCuBE Collaboration",
+        root_doc,
+        "{PROJECT_SLUG_NAME}.tex",
+        DOCUMENT_DESCRIPTION,
+        author,
         "manual",
     ),
 ]
@@ -265,7 +293,15 @@
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "mxcube3", u"MXCuBE3 Documentation", [author], 1)]
+man_pages = [
+    (
+        root_doc,
+        PROJECT_SLUG_NAME,
+        DOCUMENT_DESCRIPTION,
+        [author],
+        1,
+    ),
+]
 
 # If true, show URL addresses after external links.
 # man_show_urls = False
@@ -278,12 +314,12 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
     (
-        master_doc,
-        "MXCuBE3",
-        u"MXCuBE3 Documentation",
+        root_doc,
+        PROJECT_SLUG_NAME,
+        project,
         author,
-        "MXCuBE3",
-        "One line description of project.",
+        project,
+        DOCUMENT_DESCRIPTION,
         "Miscellaneous",
     ),
 ]

docs/source/contents.rst

@@ -0,0 +1,13 @@
+#################
+Table of contents
+#################
+
+Contents:
+
+.. toctree::
+    :glob:
+    :titlesonly:
+
+    *
+    dev/index
+    rest-api/index

docs/source/dev/contributing.md

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

docs/source/dev/dev-env.rst

@@ -0,0 +1,8 @@
+***********************
+Development environment
+***********************
+
+See instructions to prepare a development environment on the |wikilink|_ .
+
+.. |wikilink| replace:: |project| wiki
+.. _wikilink: https://github.com/mxcube/mxcubeweb/wiki

docs/source/dev/index.rst

@@ -0,0 +1,9 @@
+#######################
+Developer documentation
+#######################
+
+.. toctree::
+    :glob:
+    :titlesonly:
+
+    *

docs/source/Login.rst → docs/source/dev/login.rst

@@ -1,5 +1,6 @@
+*****
 Login
-=====
+*****
 
 MXCuBE web sessions are meant to expire when there is no activity,
 as opposed to a typical web session that expires when the browser is closed.
@@ -23,10 +24,3 @@ Every time the *refresh* endpoint is called,
 the browser session cookie is refreshed,
 meaning its expiration timestamp is pushed back in the future
 for as much as the value stored in ``PERMANENT_SESSION_LIFETIME``.
-
-
-Login API
----------
-
-.. autoflask:: mxcube3.routes.Login:mxcube
-    :endpoints: login, signout, loginInfo, get_initial_state, proposal_samples

docs/source/index.md

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

docs/source/rest-api/beamline.rst

@@ -0,0 +1,6 @@
+*****************
+Beamline REST API
+*****************
+
+.. autoflask:: mxcube3:server.flask
+    :blueprints: beamline

docs/source/rest-api/detector.rst

@@ -0,0 +1,6 @@
+*****************
+Detector REST API
+*****************
+
+.. autoflask:: mxcube3:server.flask
+    :blueprints: detector

docs/source/rest-api/diffractometer.rst

@@ -0,0 +1,6 @@
+***********************
+Diffractometer REST API
+***********************
+
+.. autoflask:: mxcube3:server.flask
+    :blueprints: diffractometer