Fix documentation pages

fabcor-maxiv · Sep 25, 2023 · f7602a7 · f7602a7
1 parent 51f32b1
commit f7602a7
Show file tree

Hide file tree

Showing 25 changed files with 428 additions and 1,259 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -c .
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build

diff --git a/docs/source/conf.py → docs/conf.py b/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",
     ),
 ]

diff --git a/docs/source/Beamline.rst b/docs/source/Beamline.rst
diff --git a/docs/source/Collection.rst b/docs/source/Collection.rst
diff --git a/docs/source/Queue.rst b/docs/source/Queue.rst
diff --git a/docs/source/Sample.rst b/docs/source/Sample.rst
diff --git a/docs/source/SampleCentring.rst b/docs/source/SampleCentring.rst
diff --git a/docs/source/contents.rst b/docs/source/contents.rst
@@ -0,0 +1,13 @@
+#################
+Table of contents
+#################
+
+Contents:
+
+.. toctree::
+    :glob:
+    :titlesonly:
+
+    *
+    dev/index
+    rest-api/index
diff --git a/docs/source/dev/contributing.md b/docs/source/dev/contributing.md
@@ -0,0 +1,2 @@
+```{include} ../../../CONTRIBUTING.md
+```
diff --git a/docs/source/dev/dev-env.rst b/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
diff --git a/docs/source/dev/index.rst b/docs/source/dev/index.rst
@@ -0,0 +1,9 @@
+#######################
+Developer documentation
+#######################
+
+.. toctree::
+    :glob:
+    :titlesonly:
+
+    *
diff --git a/docs/source/Login.rst → docs/source/dev/login.rst b/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
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -0,0 +1,2 @@
+```{include} ../../README.md
+```
diff --git a/docs/source/index.rst b/docs/source/index.rst
diff --git a/docs/source/rest-api/beamline.rst b/docs/source/rest-api/beamline.rst
@@ -0,0 +1,6 @@
+*****************
+Beamline REST API
+*****************
+
+.. autoflask:: mxcube3:server.flask
+    :blueprints: beamline
diff --git a/docs/source/rest-api/detector.rst b/docs/source/rest-api/detector.rst
@@ -0,0 +1,6 @@
+*****************
+Detector REST API
+*****************
+
+.. autoflask:: mxcube3:server.flask
+    :blueprints: detector
diff --git a/docs/source/rest-api/diffractometer.rst b/docs/source/rest-api/diffractometer.rst
@@ -0,0 +1,6 @@
+***********************
+Diffractometer REST API
+***********************
+
+.. autoflask:: mxcube3:server.flask
+    :blueprints: diffractometer
diff --git a/docs/source/rest-api/index.rst b/docs/source/rest-api/index.rst
@@ -0,0 +1,9 @@
+########
+REST API
+########
+
+.. toctree::
+    :glob:
+    :titlesonly:
+
+    *
diff --git a/docs/source/rest-api/lims.rst b/docs/source/rest-api/lims.rst
@@ -0,0 +1,6 @@
+*************
+LIMS REST API
+*************
+
+.. autoflask:: mxcube3:server.flask
+    :blueprints: lims
diff --git a/docs/source/rest-api/login.rst b/docs/source/rest-api/login.rst
@@ -0,0 +1,6 @@
+**************
+Login REST API
+**************
+
+.. autoflask:: mxcube3:server.flask
+    :blueprints: login
diff --git a/docs/source/rest-api/queue.rst b/docs/source/rest-api/queue.rst
@@ -0,0 +1,6 @@
+**************
+Queue REST API
+**************
+
+.. autoflask:: mxcube3:server.flask
+    :blueprints: queue
diff --git a/docs/source/rest-api/remote-access.rst b/docs/source/rest-api/remote-access.rst
@@ -0,0 +1,6 @@
+**********************
+Remote access REST API
+**********************
+
+.. autoflask:: mxcube3:server.flask
+    :blueprints: remote_access
diff --git a/docs/source/rest-api/sample-view.rst b/docs/source/rest-api/sample-view.rst
@@ -0,0 +1,6 @@
+********************
+Sample view REST API
+********************
+
+.. autoflask:: mxcube3:server.flask
+    :blueprints: sampleview