Skip to content

Conversation

sadielbartholomew
Copy link
Member

@sadielbartholomew sadielbartholomew commented Aug 14, 2025

Close #350.

Includes fixing some minor docs issues along the way (a few typos where cf. was used instead of cfdm., a broken text link, and some old class stubs that are no longer valid classes which broke the build).

The main fixes to get newer version of Sphinx to behave as we'd like as not mess up the API reference structuring, as per this PR are:

  • to set autosummary_generate = False in the conf.py configuration, because when enabled that meant the docs/source/class/cfdm.*; class obect files with our custom lists structure we being overwritten by those generated from some templates;
  • to provide a Jinja2 template for the base object in the location it expects, namely under a subdirectory _templates/autosummary/base.rst of the _templates location set in the conf.py (we had ours only in the parent _templates/ with no such directory) - note we need this still given autosummary further used in the custom class files we have, so we still rely on some templates to cover functions and method etc. stubs, even if we have our own top-level class reference RST files;
  • change implicit labels such as :ref:`cfdm.Object <cfdm-Object>` to well-defined Python object references namely :py:class:`cfdm.Object` because the former were allowed in old Sphinx versions from being assumed/taken as implicit references, but newer versions are stricter so these aren't valid there;
  • in our functions template, replace the auto-gen'd function Junja2 injection of {{ fullname }} with {{ objname }}, because under the new Sphinx versions and/or any the changes above, the linking on the list of functions in functions.rst had otherwise broken.

@sadielbartholomew sadielbartholomew self-assigned this Aug 14, 2025
@sadielbartholomew sadielbartholomew added the documentation Improvements or additions to documentation label Aug 14, 2025
Copy link
Contributor

@davidhassell davidhassell left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi Sadie,

Aside from my comment on tutorial.rst this looks great! Very many thanks for finally sorting this out :-)

@sadielbartholomew
Copy link
Member Author

The second commit added, 4bb9cf1, fixes one more issue I spotted in final self-review of the docs generated with the new versions, namely that the functions pages weren't linking properly.

Merging without re-review so I can get on with preparing the new release (I trust that neither of my two commits since are controversial).

@sadielbartholomew sadielbartholomew merged commit fa6e98c into NCAS-CMS:main Aug 15, 2025
@sadielbartholomew sadielbartholomew deleted the docs-infra-update branch August 15, 2025 17:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Reconfigure Sphinx & extensions for use of latest versions
2 participants