docs/theme-updates

[alphasentaurii]

Description

This PR updates documentation configuration options to make Read the Docs look and feel consistent with other ASDF subprojects.

Tasks

• run pre-commit on your machine
• run pytest on your machine
• Does this PR add new features and / or change user-facing code / API? (if not, label with no-changelog-entry-needed)
  • write news fragment(s) in changes/: echo "changed something" > changes/<PR#>.<changetype>.rst (see below for change types)
  • update relevant docstrings and / or docs/ page
  • for any new features, add unit tests

news fragment change types...

• changes/<PR#>.feature.rst: new feature
• changes/<PR#>.bugfix.rst: bug fix
• changes/<PR#>.doc.rst: documentation change
• changes/<PR#>.removal.rst: deprecation or removal of public API
• changes/<PR#>.general.rst: infrastructure or miscellaneous change

[braingram]

Thanks! A few comments/questions.

[braingram]

Poking around the docs I also noticed that the left menu is no longer collapsing the autogenerated API documentation.
Compare https://asdf.readthedocs.io/en/latest/asdf/developer_api.html
to https://asdf--1897.org.readthedocs.build/en/1897/asdf/developer_api.html
Note that the side menu with this PR no longer collapses classes/functions by module. Is this a settings issue or a byproduct of the theme?

EDIT: same for non-autodoc docs comparing
https://asdf--1897.org.readthedocs.build/en/1897/asdf/features.html
to
https://asdf.readthedocs.io/en/latest/asdf/features.html#

[alphasentaurii]

Poking around the docs I also noticed that the left menu is no longer collapsing the autogenerated API documentation. Compare https://asdf.readthedocs.io/en/latest/asdf/developer_api.html to https://asdf--1897.org.readthedocs.build/en/1897/asdf/developer_api.html Note that the side menu with this PR no longer collapses classes/functions by module. Is this a settings issue or a byproduct of the theme?

EDIT: same for non-autodoc docs comparing https://asdf--1897.org.readthedocs.build/en/1897/asdf/features.html to https://asdf.readthedocs.io/en/latest/asdf/features.html#

The left menu on the old/current theme is visible on the right hand side under "On this page" in the new theme. The left sidebar is a now a Toc Tree of the pages, while the rather than the contents of the page you're viewing (which is now on the right). The existing theme displays a mix of the currently viewed page's headings as well as other pages underneath it - so that change here is putting pages on left sidebar, current page contents on the right.

[braingram]

Poking around the docs I also noticed that the left menu is no longer collapsing the autogenerated API documentation. Compare https://asdf.readthedocs.io/en/latest/asdf/developer_api.html to https://asdf--1897.org.readthedocs.build/en/1897/asdf/developer_api.html Note that the side menu with this PR no longer collapses classes/functions by module. Is this a settings issue or a byproduct of the theme?
EDIT: same for non-autodoc docs comparing https://asdf--1897.org.readthedocs.build/en/1897/asdf/features.html to https://asdf.readthedocs.io/en/latest/asdf/features.html#

The left menu on the old/current theme is visible on the right hand side under "On this page" in the new theme. The left sidebar is a now a Toc Tree of the pages, while the rather than the contents of the page you're viewing (which is now on the right). The existing theme displays a mix of the currently viewed page's headings as well as other pages underneath it - so that change here is putting pages on left sidebar, current page contents on the right.

Can we get something more similar to the old behavior back with the new theme? The goal is to preserve the TOC nesting that was previously shown on the left menu. To provide an example to explain the motivation:
https://asdf.readthedocs.io/en/latest/asdf/arrays.html
shows:

• a left menu with the nested TOC location: Core Features -> Array Data -> Saving Arrays
• the top header shows a more shallow nested TOC location: Core Features -> Saving Arrays (this one is redundant but I know I have used this top header in the past to navigate the documentation)

Whereas with the current configuration in this PR:
https://asdf--1897.org.readthedocs.build/en/1897/asdf/arrays.html#

• the left menu shows TOC location: Core Features -> Saving Arrays
  and I see no place where the Array Data nesting is shown.

[alphasentaurii]

Poking around the docs I also noticed that the left menu is no longer collapsing the autogenerated API documentation. Compare https://asdf.readthedocs.io/en/latest/asdf/developer_api.html to https://asdf--1897.org.readthedocs.build/en/1897/asdf/developer_api.html Note that the side menu with this PR no longer collapses classes/functions by module. Is this a settings issue or a byproduct of the theme?
EDIT: same for non-autodoc docs comparing https://asdf--1897.org.readthedocs.build/en/1897/asdf/features.html to https://asdf.readthedocs.io/en/latest/asdf/features.html#

The left menu on the old/current theme is visible on the right hand side under "On this page" in the new theme. The left sidebar is a now a Toc Tree of the pages, while the rather than the contents of the page you're viewing (which is now on the right). The existing theme displays a mix of the currently viewed page's headings as well as other pages underneath it - so that change here is putting pages on left sidebar, current page contents on the right.

Can we get something more similar to the old behavior back with the new theme? The goal is to preserve the TOC nesting that was previously shown on the left menu. To provide an example to explain the motivation: https://asdf.readthedocs.io/en/latest/asdf/arrays.html shows:

• a left menu with the nested TOC location: Core Features -> Array Data -> Saving Arrays
• the top header shows a more shallow nested TOC location: Core Features -> Saving Arrays (this one is redundant but I know I have used this top header in the past to navigate the documentation)

Whereas with the current configuration in this PR: https://asdf--1897.org.readthedocs.build/en/1897/asdf/arrays.html#

• the left menu shows TOC location: Core Features -> Saving Arrays
  and I see no place where the Array Data nesting is shown.

I think so let me work on that

[alphasentaurii]

Poking around the docs I also noticed that the left menu is no longer collapsing the autogenerated API documentation. Compare https://asdf.readthedocs.io/en/latest/asdf/developer_api.html to https://asdf--1897.org.readthedocs.build/en/1897/asdf/developer_api.html Note that the side menu with this PR no longer collapses classes/functions by module. Is this a settings issue or a byproduct of the theme?
EDIT: same for non-autodoc docs comparing https://asdf--1897.org.readthedocs.build/en/1897/asdf/features.html to https://asdf.readthedocs.io/en/latest/asdf/features.html#

The left menu on the old/current theme is visible on the right hand side under "On this page" in the new theme. The left sidebar is a now a Toc Tree of the pages, while the rather than the contents of the page you're viewing (which is now on the right). The existing theme displays a mix of the currently viewed page's headings as well as other pages underneath it - so that change here is putting pages on left sidebar, current page contents on the right.

Can we get something more similar to the old behavior back with the new theme? The goal is to preserve the TOC nesting that was previously shown on the left menu. To provide an example to explain the motivation: https://asdf.readthedocs.io/en/latest/asdf/arrays.html shows:

• a left menu with the nested TOC location: Core Features -> Array Data -> Saving Arrays
• the top header shows a more shallow nested TOC location: Core Features -> Saving Arrays (this one is redundant but I know I have used this top header in the past to navigate the documentation)

Whereas with the current configuration in this PR: https://asdf--1897.org.readthedocs.build/en/1897/asdf/arrays.html#

• the left menu shows TOC location: Core Features -> Saving Arrays
  and I see no place where the Array Data nesting is shown.

I think so let me work on that

I've tried setting up User Api to include its 3 sections in the left-hand TOC. In order to do this however I needed to split these up into their own pages. (Sphinx's toctree directive only allows references to actual pages, not page sections.) Let me know what you think and if you'd like to keep this or if I should revert back to how it was: https://asdf--1897.org.readthedocs.build/en/1897/asdf/user_api/asdf_package.html (note you may need to refresh page/clear cookies or open in incognito window)

[braingram]

One minor comment about the version/release in the sphinx conf then this is good to go.

A TBD docs cleanup seems worthwhile to take full advantage of the new theme but it makes sense to me to have that in follow-up PRs (since those will involve content changes).

[braingram]

LGTM. Thanks for all your work on this.