docs/asdf-website-changes

[alphasentaurii]

• Use furo theme for consistency with parent asdf website
• Remove intro page (contents moved to asdf website overview page: https://asdf-website.readthedocs.io/en/latest/overview.html)
• Improved toc tree / page hierarchy
• added new logo
• configuration minor fixes
• allow livehtml preview during doc changes

[braingram]

For the pre commit errors one option is to install and run pre-commit locally (as it will autofix many errors):

pip install pre-commit
pre-commit run --all-files

[braingram]

I think for the test failures updating this fixture might be required:

asdf-standard/tests/conftest.py

Line 94 in 35a6132

def docs_schema_ids():

or changing the docs layout to match what's on main (although I'm in favor of updating the fixture).

One thing to consider is that external packages can link to the docs via sphinx-asdf managed links. I think practically this is only used by rad at the moment.

For example, rad currently links back to the asdf-standard docs with an asdf_schema_reference_mappings:
https://github.com/spacetelescope/rad/blob/3d43b917b31b3d8f0301ae95b5ae1dca3e9eedbf/docs/conf.py#L200
This allows schema uris in the rad schemas that start with http://stsci.edu/schemas/asdf/ to generate valid links back to the schema in the standard. For example the file_date schema links to time-1.1.0. I think that link still works with this PR:
https://asdf-standard--446.org.readthedocs.build/en/446/generated/stsci.edu/asdf/time/time-1.1.0.html
so that makes me think the test fixture needs updating to see the new docs layout.

[alphasentaurii]

I think for the test failures updating this fixture might be required:

asdf-standard/tests/conftest.py

Line 94 in 35a6132

def docs_schema_ids():

or changing the docs layout to match what's on main (although I'm in favor of updating the fixture).
One thing to consider is that external packages can link to the docs via sphinx-asdf managed links. I think practically this is only used by rad at the moment.

For example, rad currently links back to the asdf-standard docs with an asdf_schema_reference_mappings: https://github.com/spacetelescope/rad/blob/3d43b917b31b3d8f0301ae95b5ae1dca3e9eedbf/docs/conf.py#L200 This allows schema uris in the rad schemas that start with http://stsci.edu/schemas/asdf/ to generate valid links back to the schema in the standard. For example the file_date schema links to time-1.1.0. I think that link still works with this PR: https://asdf-standard--446.org.readthedocs.build/en/446/generated/stsci.edu/asdf/time/time-1.1.0.html so that makes me think the test fixture needs updating to see the new docs layout.

Yes - the "generated" file links are all the same as before. The only true change is the structure of the pages. I did have to update the test_docs.py test to look for asdf.rst since that is a new file (its contents were moved from schemas/index.rst). Most of the changes I made were for the sake of improving the TOC tree and breaking up sections into separate pages where it made sense. In retrospect I'm not sure it was worth the trouble but now all the tests are passing so we'll go with it. I'll be on standby if some obscure link has been broken but as far as I can tell everything is in working order.

[alphasentaurii]

Is there a way to configure the syntax highlighting for the new theme to provide more colors for the yaml?

Yes, that can be configured via sphinx's pygments_style setting in conf.py and is also fully customizable. I'll look at the options and see if I can find one more suitable (i.e. similar to the sphinx theme)

[braingram]

Thanks for putting this together. Here's a round of comments. Overall the changes look good to me with a few suggestions/questions about the:

• heading changes
• doc reorganization

I assume we'll want to make similar changes in other asdf-format repos to at least keep a consistent theme. It would be helpful to split up those PRs into smaller PRs with:

• theme changes
• reorganization
• content changes

I worry with this PR that I missed some of the content changes due to the reorganization.

[braingram]

Suggested change

	Schema Design and Editing
	Schema Design and Editing

I am in favor of the old name:
https://asdf-standard.readthedocs.io/en/1.1.1/schemas.html#designing-a-new-tag-and-schema
"Designing a new tag and schema" since it makes more of a distinction between the "tag" and "schema".

[braingram]

On main this shows up as "Appendix A: Embedding ASDF in FITS" in the TOC. With this PR it loses the "Appendix A" part. I think we should keep that as an appendix to avoid confusion about this being something we generally support (which we don't).

[braingram]

I'd be in favor of removing it from the top level TOC if that's easier.

[braingram]

What's the need for moving these out of a "schemas" subdirectory? I'm in favor of keeping to old structure if it doesn't cause complications (since it's easier to tell what portions of the docs are describing schema resources).

[braingram]

The manifests aren't schemas. I'm in favor of keeping the old heading:
"ASDF Standard Resources"