Improvements to the documentation

A few miscellaneous improvements to the documentation, including some content restructuring and configuration updates

.gitignore

@@ -16,6 +16,7 @@ __pycache__/
 
 # documentation outputs
 /docs/_build/
-/docs/api/
+/docs/api/*.rst
+!/docs/api/gwdatafind.rst
 !/docs/api/gwdatafind.utils.rst
 *.automodapi

.gitlab-ci.yml

@@ -50,6 +50,7 @@ include:
 
   - component: $CI_SERVER_FQDN/computing/gitlab/components/sphinx/build@1
     inputs:
+      apt_packages: graphviz
       requirements: ".[docs]"
 
 

README.md

@@ -7,8 +7,7 @@ Gravitational-Wave Frame (GWF) files containing data from the current
 gravitational-wave detectors.
 
 [![PyPI version](https://badge.fury.io/py/gwdatafind.svg)](http://badge.fury.io/py/gwdatafind)
-[![Linux status](https://git.ligo.org/lscsoft/gwdatafind/badges/main/pipeline.svg)](https://git.ligo.org/lscsoft/gwdatafind/commits/main)
-[![Windows status](https://ci.appveyor.com/api/projects/status/js6gql8960qa9pkl?svg=true)](https://ci.appveyor.com/project/duncanmmacleod/gwdatafind)
+[![Conda version](https://img.shields.io/conda/vn/conda-forge/gwdatafind.svg)](https://anaconda.org/conda-forge/gwdatafind/)
 [![License](https://img.shields.io/pypi/l/gwdatafind.svg)](https://choosealicense.com/licenses/gpl-3.0/)
 [![Documentation status](https://readthedocs.org/projects/gwdatafind/badge/?version=latest)](https://gwdatafind.readthedocs.io/en/latest/?badge=latest)
 

docs/api.rst

-===================
- API documentation
-===================
-
-.. automodapi:: gwdatafind
-   :no-inheritance-diagram:
-   :no-heading:
-   :no-main-docstr:
-   :headings: =-
-   :skip: Session
-
-
-Submodules
-----------
-
-.. toctree::
-
-   api/gwdatafind.utils

docs/api/gwdatafind.rst

+############
+`gwdatafind`
+############
+
+.. automodapi:: gwdatafind
+   :no-heading:
+   :headings: =-

docs/api/gwdatafind.utils.rst

+##################
+`gwdatafind.utils`
+##################
+
 .. automodapi:: gwdatafind.utils
+    :no-heading:

docs/auth.rst

@@ -33,7 +33,7 @@ GWDataFind servers may be operated with support for
 `SciTokens <https://scitokens.org>`__, an implementation of
 JSON Web Tokens designed for distributed scientific computing.
 
-When using the :doc:`API <api>`, the following keyword arguments
+When using :doc:`api/gwdatafind`, the following keyword arguments
 can be used with all functions to control the use of SciTokens:
 
 ``token``
@@ -83,7 +83,7 @@ proxies as authorisation credentials.
 This requires the X.509 credential _subject_ to be known to the server
 ahead of time.
 
-When using the :doc:`API <api>`, the following keyword arguments
+When using :doc:`api/gwdatafind`, the following keyword arguments
 can be used to control the use of X.509 credentials:
 
 ``cert``

docs/commandline.rst

+================
+``gw_data_find``
+================
+
+GWDataFind queries can be made using the command-line interface
+accessible via module execution (``python -m gwdatafind``) or
+the ``gw_data_find`` entry point script:
+
+.. argparse::
+    :module: gwdatafind.__main__
+    :func: command_line
+    :prog: gw_data_find
+    :nodescription:

docs/conf.py

-# gwdatafind documentation build configuration file
+# Copyright (C) 2025 Cardiff University
+#
+# This file is part of GWDataFind.
+#
+# GWDataFind is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# GWDataFind is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GWDataFind.  If not, see <http://www.gnu.org/licenses/>.
+
+"""GWDataFind documentation configuration file."""
+
+from datetime import (
+    datetime,
+    timezone,
+)
 
-import inspect
-import re
-import sys
-from os import getenv
-from pathlib import Path
+import sphinx_github_style
 
 import gwdatafind
 
 # -- metadata
 
 project = "gwdatafind"
-copyright = "2018-2025, Cardiff University"
+copyright = f"{datetime.now(tz=timezone.utc).date().year}, Cardiff University"
 author = "Duncan Macleod"
 release = gwdatafind.__version__
-version = re.split(r"[\w-]", gwdatafind.__version__)[0]
+version = release.split("+", 1)[0]
 
 # -- config
 
@@ -26,6 +44,7 @@ default_role = "obj"
 # -- theme
 
 html_theme = "furo"
+html_title = f"{project} {version}"
 
 html_theme_options = {
     "footer_icons": [
@@ -52,6 +71,7 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.linkcode",
+    "sphinxarg.ext",
     "sphinx_automodapi.automodapi",
     "sphinx_copybutton",
     "sphinxarg.ext",
@@ -60,99 +80,33 @@ extensions = [
 # automodapi
 automodapi_inherited_members = False
 
+# copybutton
+copybutton_prompt_text = " |".join((  # noqa: FLY002
+    ">>>",
+    r"\.\.\.",
+    r"\$"
+    r"In \[\d*\]:",
+    r" {2,5}\.\.\.:",
+    " {5,8}: ",
+))
+copybutton_prompt_is_regexp = True
+copybutton_line_continuation_character = "\\"
+
 # intersphinx
-intersphinx_mapping = {
-    "igwn-auth-utils": (
-        "https://igwn-auth-utils.readthedocs.io/en/stable/",
-        None,
-    ),
-    "igwn-segments": (
-        "https://igwn-segments.readthedocs.io/en/stable/",
-        None,
-    ),
-    "python": (
-        "https://docs.python.org/",
-        None,
-    ),
-    "requests": (
-        "https://requests.readthedocs.io/en/stable/",
-        None,
-    ),
-    "scitokens": (
-        "https://scitokens.readthedocs.io/en/stable/",
-        None,
-    ),
-}
+intersphinx_mapping = {key: (value, None) for key, value in {
+    "igwn-auth-utils": "https://igwn-auth-utils.readthedocs.io/en/stable/",
+    "igwn-segments": "https://igwn-segments.readthedocs.io/en/stable/",
+    "python": "https://docs.python.org/",
+    "requests": "https://requests.readthedocs.io/en/stable/",
+    "scitokens": "https://scitokens.readthedocs.io/en/stable/",
+}.items()}
+
+# linkcode
+linkcode_url = sphinx_github_style.get_linkcode_url(
+    blob=sphinx_github_style.get_linkcode_revision("head"),
+    url="https://git.ligo.org/computing/gwdatafind/client",
+)
+linkcode_resolve = sphinx_github_style.get_linkcode_resolve(linkcode_url)
 
 # napoleon
 napoleon_use_rtype = False
-
-
-# -- linkcode
-
-def _project_git_ref(version, prefix="v"):
-    """Returns the git reference for the given full release version.
-    """
-    # handle builds in CI
-    if getenv("GITLAB_CI"):
-        return getenv("CI_COMMIT_REF")
-    if getenv("GITHUB_ACTIONS"):
-        return getenv("GITHUB_SHA")
-    # otherwise use the project metadata
-    _setuptools_scm_version_regex = re.compile(
-        r"\+g(\w+)(?:\Z|\.)",
-    )
-    if match := _setuptools_scm_version_regex.search(version):
-        return match.groups()[0]
-    return f"{prefix}{version}"
-
-
-PROJECT_GIT_REF = _project_git_ref(release, prefix="")
-PROJECT_PATH = Path(gwdatafind.__file__).parent
-PROJECT_URL = getenv(
-    "CI_PROJECT_URL",
-    "https://git.ligo.org/computing/gwdatafind/client",
-)
-PROJECT_BLOB_URL = f"{PROJECT_URL}/blob/{PROJECT_GIT_REF}/{PROJECT_PATH.name}"
-
-
-def linkcode_resolve(domain, info):
-    """Determine the URL corresponding to Python object.
-    """
-    if domain != "py" or not info["module"]:
-        return None
-
-    def find_source(module, fullname):
-        """Construct a source file reference for an object reference.
-        """
-        # resolve object
-        obj = sys.modules[module]
-        for part in fullname.split("."):
-            obj = getattr(obj, part)
-        # get filename relative to project
-        filename = Path(
-            inspect.getsourcefile(obj),  # type: ignore [arg-type]
-        ).relative_to(PROJECT_PATH).as_posix()
-        # get line numbers of this object
-        lines, lineno = inspect.findsource(obj)
-        if lineno:
-            start = lineno + 1  # 0-index
-            end = lineno + len(inspect.getblock(lines[lineno:]))
-        else:
-            start = end = 0
-        return filename, start, end
-
-    try:
-        path, start, end = find_source(info["module"], info["fullname"])
-    except (
-        AttributeError,  # object not found
-        OSError,  # file not found
-        TypeError,  # source for object not found
-        ValueError,  # file not from this project
-    ):
-        return None
-
-    url = f"{PROJECT_BLOB_URL}/{path}"
-    if start:
-        url += f"#L{start}-L{end}"
-    return url

docs/index.rst

-
 ##########
 GWDataFind
 ##########
 
-.. toctree::
-    :hidden:
+The client library for the GWDataFind service.
 
-    GWDatafind <self>
+.. image:: https://badge.fury.io/py/gwdatafind.svg
+    :target: https://badge.fury.io/py/gwdatafind
+    :alt: gwdatafind PyPI release badge
 
-The client library for the GWDataFind service.
+.. image:: https://img.shields.io/conda/vn/conda-forge/gwdatafind.svg
+    :target: https://anaconda.org/conda-forge/gwdatafind/
+    :alt: gwdatafind conda-forge release badge
+
+.. image:: https://img.shields.io/pypi/l/gwdatafind.svg
+    :target: https://choosealicense.com/licenses/gpl-3.0/
+    :alt: gwdatafind license
+
+.. raw:: html
+
+    <br>
+
+.. image:: https://img.shields.io/gitlab/issues/open/computing%2Fgwdatafind%2Fclient?gitlab_url=https%3A%2F%2Fgit.ligo.org
+    :target: https://git.ligo.org/computing/gwdatafind/client/issues/
+    :alt: GitLab Issues
+
+.. image:: https://img.shields.io/gitlab/merge-requests/open/computing%2Fgwdatafind%2Fclient?gitlab_url=https%3A%2F%2Fgit.ligo.org
+    :target: https://git.ligo.org/computing/gwdatafind/client/merge_requests/
+    :alt: GitLab Merge Requests
 
 .. toctree::
     :caption: Documentation
@@ -21,6 +39,13 @@ The client library for the GWDataFind service.
 
 .. toctree::
     :caption: Reference
-    :maxdepth: 2
+    :maxdepth: 1
+
+    api/gwdatafind
+    api/gwdatafind.utils
+
+.. toctree::
+    :caption: Command-line interface
+    :maxdepth: 1
 
-    api
+    commandline

docs/install.rst

@@ -70,10 +70,9 @@ RedHat / CentOS / Scientific / Rocky Linux
     dnf install gwdatafind
 
 See the IGWN Computing Guide software repositories entries for
-`Scientific Linux 7
-<https://computing.docs.ligo.org/guide/software/sl7/>`__
-or
 `Rocky Linux 8 <https://computing.docs.ligo.org/guide/software/rl8/>`__
+or
+`Rocky Linux 9 <https://computing.docs.ligo.org/guide/software/rl9/>`__
 for instructions on how to configure the required IGWN Yum repositories.
 
 To install the Python 3 library only (and not any command-line entry points):

docs/intro.rst

@@ -63,10 +63,4 @@ Command-line interface
 
 GWDataFind also provides a command-line interface accessible via
 module execution (``python -m gwdatafind``) or the ``gw_data_find``
-entry point script:
-
-.. argparse::
-    :module: gwdatafind.__main__
-    :func: command_line
-    :prog: gw_data_find
-    :nodescription:
+entry point script. See :doc:`commandline`.

pyproject.toml

@@ -45,11 +45,11 @@ dynamic = [
 [project.optional-dependencies]
 docs = [
   "furo",
-  "numpydoc",
-  "Sphinx >= 4.4.0",
+  "Sphinx >=4.4.0",
   "sphinx-argparse",
-  "sphinx_automodapi",
+  "sphinx-automodapi",
   "sphinx-copybutton",
+  "sphinx-github-style",
 ]
 test = [
   "pytest >= 3.9.3",