Fix documentation pages

fabcor-maxiv · Sep 22, 2023 · bf925f1 · bf925f1
1 parent 9cc9e9e
commit bf925f1
Show file tree

Hide file tree

Showing 24 changed files with 382 additions and 1,252 deletions.
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/conf.py b/docs/source/conf.py
@@ -12,18 +12,16 @@
 # 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 mxcube3
+
+mxcube3.build_server_and_config(argv=[])
 
 # 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,32 +33,27 @@
 # 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", ".md"]
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = "index"
+master_doc = "contents"
 
 # General information about the project.
-project = u"MXCuBE3"
-copyright = u"2015, MXCuBE Collaboration"
-author = u"MXCuBE Collaboration"
+project = "MXCuBE Web"
+copyright = f"{datetime.datetime.today().year}, MXCuBE Collaboration"
+author = "MXCuBE Collaboration"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -76,7 +69,7 @@
 #
 # 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:
@@ -149,7 +142,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 +158,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 +211,7 @@
 # html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = "MXCuBE3doc"
+htmlhelp_basename = "MXCuBE-Web-doc"
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -233,9 +232,9 @@
 latex_documents = [
     (
         master_doc,
-        "MXCuBE3.tex",
-        u"MXCuBE3 Documentation",
-        u"MXCuBE Collaboration",
+        "MXCuBE-Web.tex",
+        "MXCuBE Web Documentation",
+        "MXCuBE Collaboration",
         "manual",
     ),
 ]
@@ -265,7 +264,7 @@
 
 # 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 = [(master_doc, "mxcube-web", "MXCuBE web Documentation", [author], 1)]
 
 # If true, show URL addresses after external links.
 # man_show_urls = False
@@ -279,11 +278,11 @@
 texinfo_documents = [
     (
         master_doc,
-        "MXCuBE3",
-        u"MXCuBE3 Documentation",
+        "MXCuBE-web",
+        "MXCuBE Web Documentation",
         author,
-        "MXCuBE3",
-        "One line description of project.",
+        "MXCuBE Web",
+        "This is the documentation for MXCuBE Web.",
         "Miscellaneous",
     ),
 ]

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,6 @@
+***********************
+Development environment
+***********************
+
+See instructions to prepare a development environment
+on the `MXCuBE Web wiki <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