Upgrade readthedocs to PyData Sphinx Theme (#323)

ratt-ru · Oct 31, 2024 · 51b9640 · 51b9640
1 parent 9551eef
commit 51b9640
Show file tree

Hide file tree

Showing 8 changed files with 46 additions and 118 deletions.
diff --git a/.github/workflows/readthedocs.yml b/.github/workflows/readthedocs.yml
@@ -0,0 +1,22 @@
+# .github/workflows/documentation-links.yml
+
+name: readthedocs/actions
+on:
+  pull_request_target:
+    types:
+      - opened
+    # Execute this action only on PRs that touch
+    # documentation files.
+    # paths:
+    #   - "doc/**"
+
+permissions:
+  pull-requests: write
+
+jobs:
+  documentation-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: "codex-africanus"
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -1,4 +1,5 @@
-# Read the Docs configuration file for Sphinx projects
+# .readthedocs.yaml
+# Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
 # Required
@@ -8,31 +9,19 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
-    # You can also specify other tool versions:
-    # nodejs: "20"
-    # rust: "1.70"
-    # golang: "1.20"
+    python: "3.12"
   jobs:
+    post_create_environment:
+      # Install poetry
+      # https://python-poetry.org/docs/#installing-manually
+      - pip install poetry==1.8.3
     post_install:
-      - pip install .
+      # Install dependencies with 'docs' dependency group
+      # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
+      # VIRTUAL_ENV needs to be set manually for now.
+      # See https://github.com/readthedocs/readthedocs.org/pull/11152/
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with doc
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
   configuration: docs/conf.py
-  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
-  # builder: "dirhtml"
-  # Fail on all warnings to avoid broken references
-  # fail_on_warning: true
-
-# Optionally build your docs in additional formats such as PDF and ePub
-# formats:
-#   - pdf
-#   - epub
-
-# Optional but recommended, declare the Python requirements required
-# to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-python:
-  install:
-    - requirements: docs/requirements.txt
diff --git a/HISTORY.rst b/HISTORY.rst
@@ -4,6 +4,7 @@ History
 
 0.3.8 (2024-09-29)
 ------------------
+* Upgrade readthedocs to PyData Sphinx Theme (:pr:`323`)
 * Upgrade backend to poetry (:pr:`322`)
 * Optimise the beam cube implementation (:pr:`320`)
 * Support an `init_state` argument into both `Term.init_fields`

diff --git a/docs/conf.py b/docs/conf.py
@@ -19,13 +19,6 @@
 # absolute, like shown here.
 #
 
-import importlib
-import os
-import sys
-
-import sphinx_rtd_theme
-import africanus
-
 # -- General configuration ---------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -94,7 +87,9 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "pydata_sphinx_theme"
+
+html_title = "Codex Africanus"
 
 # 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
@@ -114,62 +109,6 @@
 htmlhelp_basename = "africanusdoc"
 
 
-# -- Options for LaTeX output ------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass
-# [howto, manual, or own class]).
-latex_documents = [
-    (
-        master_doc,
-        "africanus.tex",
-        "Codex Africanus Documentation",
-        "Simon Perkins",
-        "manual",
-    ),
-]
-
-
-# -- Options for manual page output ------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "africanus", "Codex Africanus Documentation", [author], 1)]
-
-numpydoc_class_members_toctree = False
-
-# -- Options for Texinfo output ----------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (
-        master_doc,
-        "africanus",
-        "Codex Africanus Documentation",
-        author,
-        "africanus",
-        "One line description of project.",
-        "Miscellaneous",
-    ),
-]
-
 extlinks = {
     "issue": ("https://github.com/ska-sa/codex-africanus/issues/%s", "GH#%s"),
     "pr": ("https://github.com/ska-sa/codex-africanus/pull/%s", "GH#%s"),

diff --git a/docs/index.rst b/docs/index.rst
@@ -6,7 +6,6 @@ Welcome to Codex Africanus's documentation!
    :maxdepth: 2
    :caption: Contents:
 
-   readme
    installation
    usage
    cmdline-utils

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -49,31 +49,3 @@ To install the complete set of dependencies including CUDA:
 
 .. _pip: https://pip.pypa.io
 .. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
-
-
-From sources
-------------
-
-The sources for Codex Africanus can be downloaded from the `Github repo`_.
-
-You can either clone the public repository:
-
-.. code-block:: console
-
-    $ git clone git://github.com/ska-sa/codex-africanus
-
-Or download the `tarball`_:
-
-.. code-block:: console
-
-    $ curl  -OL https://github.com/ska-sa/codex-africanus/tarball/master
-
-Once you have a copy of the source, you can install it with:
-
-.. code-block:: console
-
-    $ python setup.py install
-
-
-.. _Github repo: https://github.com/ska-sa/codex-africanus
-.. _tarball: https://github.com/ska-sa/codex-africanus/tarball/master
diff --git a/docs/requirements.txt b/docs/requirements.txt
diff --git a/pyproject.toml b/pyproject.toml
@@ -41,6 +41,14 @@ tbump = "^6.11.0"
 ruff = "^0.7.1"
 pre-commit = "^4.0.1"
 
+[tool.poetry.group.doc.dependencies]
+sphinx = "^8.0.2"
+pygments = "^2.18.0"
+sphinx-copybutton = "^0.5.2"
+pydata-sphinx-theme = "^0.15.4"
+numpydoc = "^1.8.0"
+
+
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"