Docs infrastructure update to unpin from v. old Sphinx version #351
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Close #350.
Includes fixing some minor docs issues along the way (a few typos where
cf.
was used instead ofcfdm.
, 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:
autosummary_generate = False
in theconf.py
configuration, because when enabled that meant thedocs/source/class/cfdm.*
; class obect files with our custom lists structure we being overwritten by those generated from some templates;_templates/autosummary/base.rst
of the_templates
location set in theconf.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;: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;{{ fullname }}
with{{ objname }}
, because under the new Sphinx versions and/or any the changes above, the linking on the list of functions infunctions.rst
had otherwise broken.