Add documentation for using Tiled at Diamond

.copier-answers.yml

@@ -6,7 +6,7 @@ author_name: Giles Knap
 description: Tiled server with Diamond Light Source plugins
 distribution_name: dls-tiled
 docker: true
-docs_type: README
+docs_type: sphinx
 git_platform: github.com
 github_org: DiamondLightSource
 package_name: dls_tiled

.github/workflows/_docs.yml

@@ -0,0 +1,65 @@
+on:
+  workflow_call:
+
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          # Need this to get version number from last tag
+          fetch-depth: 0
+
+      - name: Install system packages
+        run: sudo apt-get install graphviz
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.0
+
+      - name: Build docs
+        run: uv run --locked tox -e docs
+
+      - name: Remove environment.pickle
+        run: rm build/html/.doctrees/environment.pickle
+
+      - name: Upload built docs artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: docs
+          path: build
+
+      - name: Sanitize ref name for docs version
+        run: echo "DOCS_VERSION=${GITHUB_REF_NAME//[^A-Za-z0-9._-]/_}" >> $GITHUB_ENV
+
+      - name: Move to versioned directory
+        run: mv build/html .github/pages/$DOCS_VERSION
+
+      - name: Write switcher.json
+        run: python .github/pages/make_switcher.py --add $DOCS_VERSION ${{ github.repository }} .github/pages/switcher.json
+
+      - name: Upload GitHub Pages artifact
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: .github/pages
+
+  # Each deployment replaces the whole site, so only main is published: a tag
+  # would replace it with just that version
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.github/workflows/ci.yml

@@ -62,11 +62,18 @@ jobs:
       contents: read
       packages: write
 
+  docs:
+    uses: ./.github/workflows/_docs.yml
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
   dist:
     uses: ./.github/workflows/_dist.yml
 
   release:
-    needs: [dist, test, container, helm]
+    needs: [dist, test, container, helm, docs]
     if: github.ref_type == 'tag'
     uses: ./.github/workflows/_release.yml
     permissions:

.github/workflows/periodic.yml

@@ -0,0 +1,13 @@
+name: Periodic
+
+on:
+  workflow_dispatch:
+  schedule:
+    # Run weekly to check URL links still resolve
+    - cron: "0 8 * * WED"
+
+jobs:
+  linkcheck:
+    uses: ./.github/workflows/_tox.yml
+    with:
+      tox: docs -- -b linkcheck

README.md

@@ -16,8 +16,15 @@ What            | Where
 :---:           | :---:
 Source          | <https://github.com/DiamondLightSource/dls-tiled>
 Docker          | `docker run ghcr.io/diamondlightsource/dls-tiled:latest`
+Documentation   | <https://diamondlightsource.github.io/dls-tiled>
 Releases        | <https://github.com/DiamondLightSource/dls-tiled/releases>
 
+<!-- README only content. Anything below this line won't be included in index.md -->
+
+For how to use Tiled at Diamond (searching, streaming, NeXus files, access
+control and the deployment architecture), see the
+[documentation](https://diamondlightsource.github.io/dls-tiled).
+
 ## Plugins
 
 Plugins are FastAPI routers. Enable one by listing it under `routers:` in the

docs/_api.rst

@@ -0,0 +1,16 @@
+:orphan:
+
+..
+   This page is not included in the TOC tree, but must exist so that the
+   autosummary pages are generated for dls_tiled and all its
+   subpackages
+
+API
+===
+
+.. autosummary::
+    :toctree: _api
+    :template: custom-module-template.rst
+    :recursive:
+
+    dls_tiled

docs/_templates/custom-module-template.rst

@@ -0,0 +1,37 @@
+{{ ('``' + fullname + '``') | underline }}
+
+{%- set filtered_members = [] %}
+{%- for item in members %}
+    {%- if item in functions + classes + exceptions + attributes %}
+        {% set _ = filtered_members.append(item) %}
+    {%- endif %}
+{%- endfor %}
+
+.. automodule:: {{ fullname }}
+    :members:
+
+    {% block modules %}
+    {% if modules %}
+    .. rubric:: Submodules
+
+    .. autosummary::
+        :toctree:
+        :template: custom-module-template.rst
+        :recursive:
+    {% for item in modules %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block members %}
+    {% if filtered_members %}
+    .. rubric:: Members
+
+    .. autosummary::
+        :nosignatures:
+    {% for item in filtered_members %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}

docs/conf.py

@@ -0,0 +1,197 @@
+"""Configuration file for the Sphinx documentation builder.
+
+This file only contains a selection of the most common options. For a full
+list see the documentation:
+https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""
+
+import sys
+from pathlib import Path
+from subprocess import check_output
+
+import requests
+
+import dls_tiled
+
+# -- General configuration ------------------------------------------------
+
+# General information about the project.
+project = "dls-tiled"
+
+# The full version, including alpha/beta/rc tags.
+release = dls_tiled.__version__
+
+# The short X.Y version.
+if "+" in release:
+    # Not on a tag, use branch name
+    root = Path(__file__).absolute().parent.parent
+    git_branch = check_output("git branch --show-current".split(), cwd=root)
+    version = git_branch.decode().strip()
+else:
+    version = release
+
+extensions = [
+    # Use this for generating API docs
+    "sphinx.ext.autodoc",
+    # and making summary tables at the top of API docs
+    "sphinx.ext.autosummary",
+    # This can parse google style docstrings
+    "sphinx.ext.napoleon",
+    # For linking to external sphinx documentation
+    "sphinx.ext.intersphinx",
+    # Add links to source code in API docs
+    "sphinx.ext.viewcode",
+    # Adds the inheritance-diagram generation directive
+    "sphinx.ext.inheritance_diagram",
+    # Add a copy button to each code block
+    "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"]
+
+# So markdown links can target headings, e.g. [text](page.md#a-heading)
+myst_heading_anchors = 3
+
+# If true, Sphinx will warn about all references where the target cannot
+# be found.
+nitpicky = True
+
+# A list of (type, target) tuples (by default empty) that should be ignored when
+# generating warnings in "nitpicky mode". Note that type should include the
+# domain name if present. Example entries would be ('py:func', 'int') or
+# ('envvar', 'LD_LIBRARY_PATH').
+nitpick_ignore = [
+    ("py:class", "NoneType"),
+    ("py:class", "'str'"),
+    ("py:class", "'float'"),
+    ("py:class", "'int'"),
+    ("py:class", "'bool'"),
+    ("py:class", "'object'"),
+    ("py:class", "'id'"),
+    ("py:class", "typing_extensions.Literal"),
+]
+
+# Both the class’ and the __init__ method’s docstring are concatenated and
+# inserted into the main body of the autoclass directive
+autoclass_content = "both"
+
+# Order the members by the order they appear in the source code
+autodoc_member_order = "bysource"
+
+# Don't inherit docstrings from baseclasses
+autodoc_inherit_docstrings = False
+
+# Document only what is in __all__
+autosummary_ignore_module_all = False
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# Output graphviz directive produced images in a scalable format
+graphviz_output_format = "svg"
+
+# The name of a reST role (builtin or Sphinx extension) to use as the default
+# role, that is, for text marked up `like this`
+default_role = "any"
+
+# The master toctree document.
+master_doc = "index"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# These patterns also affect html_static_path and html_extra_path
+exclude_patterns = ["_build"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# This means you can link things like `str` and `asyncio` to the relevant
+# docs in the python documentation.
+intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}
+
+# A dictionary of graphviz graph attributes for inheritance diagrams.
+inheritance_graph_attrs = {"rankdir": "TB"}
+
+# Ignore localhost links for periodic check that links in docs are valid
+# or Diamond hosts, which the public CI runners cannot reach
+linkcheck_ignore = [r"http://localhost:\d+/", r"https://[^/]*\.diamond\.ac\.uk"]
+
+# GitHub adds the anchors of rendered markdown with javascript
+linkcheck_anchors_ignore_for_url = [r"https://github\.com/"]
+
+# Set copy-button to ignore python and bash prompts
+# https://sphinx-copybutton.readthedocs.io/en/latest/use.html#using-regexp-prompt-identifiers
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "pydata_sphinx_theme"
+github_repo = "dls-tiled"
+github_user = "DiamondLightSource"
+switcher_json = f"https://{github_user}.github.io/{github_repo}/switcher.json"
+switcher_exists = requests.get(switcher_json).ok
+if not switcher_exists:
+    print(
+        "*** Can't read version switcher, is GitHub pages enabled? \n"
+        "    Set the Github pages source to be 'GitHub Actions' at:\n"
+        f"    https://github.com/{github_user}/{github_repo}/settings/pages",
+        file=sys.stderr,
+    )
+
+# Theme options for pydata_sphinx_theme
+# We don't check switcher because there are 3 possible states for a repo:
+# 1. New project, docs are not published so there is no switcher
+# 2. Existing project with latest copier template, switcher exists and works
+# 3. Existing project with old copier template that makes broken switcher,
+#    switcher exists but is broken
+# Point 3 makes checking switcher difficult, because the updated copier template
+# will fix the switcher at the end of the docs workflow, but never gets a chance
+# to complete as the docs build warns and fails.
+html_theme_options = {
+    "logo": {
+        "text": project,
+    },
+    "use_edit_page_button": True,
+    "github_url": f"https://github.com/{github_user}/{github_repo}",
+    "icon_links": [
+        {
+            "name": "PyPI",
+            "url": f"https://pypi.org/project/{project}",
+            "icon": "fas fa-cube",
+        }
+    ],
+    "switcher": {
+        "json_url": switcher_json,
+        "version_match": version,
+    },
+    "check_switcher": False,
+    "navbar_end": ["theme-switcher", "icon-links", "version-switcher"],
+    "navigation_with_keys": False,
+}
+
+# A dictionary of values to pass into the template engine’s context for all pages
+html_context = {
+    "github_user": github_user,
+    "github_repo": github_repo,
+    "github_version": version,
+    "doc_path": "docs",
+}
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+html_show_sphinx = False
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+html_show_copyright = False
+
+# Logo
+html_logo = "images/dls-logo.svg"
+html_favicon = html_logo

docs/explanations.md

@@ -0,0 +1,10 @@
+# Explanations
+
+Explanations of how it works and why it works that way.
+
+```{toctree}
+:maxdepth: 1
+:glob:
+
+explanations/*
+```