diff --git a/.github/workflows/readthedocs.yml b/.github/workflows/readthedocs.yml new file mode 100644 index 00000000..f50a33e4 --- /dev/null +++ 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 index 585ab23b..2e1c29db 100644 --- 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 index 9df04666..17bcc0b4 100644 --- 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 index ef6c6ba8..f4ced599 100755 --- 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 index b82030c1..f9d5b617 100644 --- 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 index 0c053c52..94892cfb 100644 --- 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 deleted file mode 100644 index fdcda53a..00000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,2 +0,0 @@ -numpydoc==1.7.0 -sphinx-rtd-theme==2.0.0 diff --git a/pyproject.toml b/pyproject.toml index 32cbc0c3..8efe4245 100644 --- 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"