fix docs

DiamondLightSource · Mar 28, 2024 · d5525c6 · d5525c6
1 parent 3a47772
commit d5525c6
Show file tree

Hide file tree

Showing 37 changed files with 233 additions and 686 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -44,8 +44,13 @@
     "sphinx_copybutton",
     # For the card element
     "sphinx_design",
+    # So we can write markdown files
+    "myst_parser",
 ]
 
+# So we can use the ::: syntax
+myst_enable_extensions = ["colon_fence"]
+
 # If true, Sphinx will warn about all references where the target cannot
 # be found.
 nitpicky = True
@@ -82,9 +87,6 @@
 # role, that is, for text marked up `like this`
 default_role = "any"
 
-# The suffix of source filenames.
-source_suffix = ".rst"
-
 # The master toctree document.
 master_doc = "index"
 
@@ -103,15 +105,6 @@
 # A dictionary of graphviz graph attributes for inheritance diagrams.
 inheritance_graph_attrs = {"rankdir": "TB"}
 
-# Common links that should be available on every page
-rst_epilog = """
-.. _Diamond Light Source: http://www.diamond.ac.uk
-.. _black: https://github.com/psf/black
-.. _ruff: https://beta.ruff.rs/docs/
-.. _mypy: http://mypy-lang.org/
-.. _pre-commit: https://pre-commit.com/
-"""
-
 # Ignore localhost links for periodic check that links in docs are valid
 linkcheck_ignore = [r"http://localhost:\d+/"]
 
@@ -126,7 +119,7 @@
 # a list of builtin themes.
 #
 html_theme = "pydata_sphinx_theme"
-github_repo = project
+github_repo = "i10-bluesky"
 github_user = "Relm-Arrowny"
 switcher_json = f"https://{github_user}.github.io/{github_repo}/switcher.json"
 switcher_exists = requests.get(switcher_json).ok
@@ -167,12 +160,7 @@
     },
     "check_switcher": False,
     "navbar_end": ["theme-switcher", "icon-links", "version-switcher"],
-    "external_links": [
-        {
-            "name": "Release Notes",
-            "url": f"https://github.com/{github_user}/{github_repo}/releases",
-        }
-    ],
+    "navigation_with_keys": False,
 }
 
 # A dictionary of values to pass into the template engine’s context for all pages
@@ -191,4 +179,4 @@
 
 # Logo
 html_logo = "images/dls-logo.svg"
-html_favicon = "images/dls-favicon.ico"
+html_favicon = html_logo
diff --git a/docs/developer/explanations/decisions.rst b/docs/developer/explanations/decisions.rst
diff --git a/docs/developer/explanations/decisions/0001-record-architecture-decisions.rst b/docs/developer/explanations/decisions/0001-record-architecture-decisions.rst
diff --git a/docs/developer/explanations/decisions/0002-switched-to-pip-skeleton.rst b/docs/developer/explanations/decisions/0002-switched-to-pip-skeleton.rst
diff --git a/docs/developer/how-to/build-docs.rst b/docs/developer/how-to/build-docs.rst
diff --git a/docs/developer/how-to/contribute.rst b/docs/developer/how-to/contribute.rst
diff --git a/docs/developer/how-to/lint.rst b/docs/developer/how-to/lint.rst
diff --git a/docs/developer/how-to/make-release.rst b/docs/developer/how-to/make-release.rst
diff --git a/docs/developer/how-to/pin-requirements.rst b/docs/developer/how-to/pin-requirements.rst
diff --git a/docs/developer/how-to/run-tests.rst b/docs/developer/how-to/run-tests.rst
diff --git a/docs/developer/how-to/static-analysis.rst b/docs/developer/how-to/static-analysis.rst
diff --git a/docs/developer/how-to/test-container.rst b/docs/developer/how-to/test-container.rst
diff --git a/docs/developer/how-to/update-tools.rst b/docs/developer/how-to/update-tools.rst