Reformat docs and move to PyData sphinx theme

[duckontheweb]

Related Issue(s):

• Closes Update sphinx theme #635

Description:

This changes the Sphinx theme for our docs from alabaster to the PyData Sphinx Theme as suggested in #635. Additionally, it makes some changes to the layout and structure of the docs to (hopefully) make them a bit more user-friendly, especially for newcomers. The layout changes were based heavily on the Bokeh documentation. Those docs are one of the examples for the PyData Sphinx Theme, and to my eye they provide a really clear landing page that helps direct different audiences to the right place in the docs.

I had also always found the API docs to be hard to navigate, especially as the codebase grew larger. I reworked those docs so that the API Reference has a landing page with cards organized by topics (either related to STAC or PySTAC) and a table of contents organized by module.

I am opening as a Draft while I get the docs to build on Sphinx as an example, and would love to get some feedback on the theme change, the high-level changes to the structure, and the API Reference changes. Updating some of the tutorials that are still out of date (e.g. #602) will be covered in separate PRs.

Preview of the new docs is available at https://pystac--687.org.readthedocs.build/en/687/.

PR Checklist:

• Code is formatted (run pre-commit run --all-files)
• Tests pass (run scripts/test)
• Documentation has been updated to reflect changes, if applicable
• This PR maintains or improves overall codebase code coverage.
• Changes are added to the CHANGELOG. See the docs for information about adding to the changelog.

[codecov-commenter]

Codecov Report

Merging #687 (65491b6) into main (70faaa5) will increase coverage by 0.00%.
The diff coverage is 100.00%.

@@           Coverage Diff           @@
##             main     #687   +/-   ##
=======================================
  Coverage   94.30%   94.30%           
=======================================
  Files          77       77           
  Lines       11249    11250    +1     
  Branches     1342     1342           
=======================================
+ Hits        10608    10609    +1     
  Misses        461      461           
  Partials      180      180           

Impacted Files	Coverage Δ
pystac/extensions/item_assets.py	84.44% <ø> (ø)
pystac/item.py	91.05% <ø> (ø)
pystac/link.py	90.85% <ø> (ø)
pystac/stac_object.py	90.81% <ø> (ø)
pystac/catalog.py	92.15% <100.00%> (+0.01%)	⬆️
pystac/collection.py	94.21% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 70faaa5...65491b6. Read the comment docs.

[duckontheweb]

@KennSmithDS @alexgleith @robintw @yeelauren You all have raised documentation-related issues in the past, so I thought I'd bring this to your attention. Let me know if any of you have any feedback on the new format/theme. Thanks!

[KennSmithDS]

@duckontheweb overall I love the changes so far, the theme is very clean and a lot easier to find the information I'm looking for. Here are some bulleted thoughts:

• Bokeh inspired boostrap theme is way more visually appealing than the old look and feel which kinda hurt my eyes
• Navigating and searching for content has dramatically improved, especially the side panel when browsing API reference
• The code snippets (especially for tutorials) are significantly easier on the eyes to read through example code and spot dependencies
• SUGGESTION: might want to put the STAC logo on the left-most side of the top navbar?

[duckontheweb]

• SUGGESTION: might want to put the STAC logo on the left-most side of the top navbar?

Yes, good idea. I considered doing this and then wasn't sure if I should use the STAC logo or if there was another one that was more specific to PySTAC. @lossyrob @cholmes Do you know if we have any PySTAC-specific logos?

[lossyrob]

There's no specific PySTAC logo - I once made one that was just the STAC logo but with the globe replaced by the Python logo. I'm not actually sure this is copacetic wrt the Python logo usage rules. I think adding the general STAC logo would be appropriate.

[duckontheweb]

Added the STAC logo in 65491b6. I'll plan on merging this today unless there is any last-minute feedback.

[alexgleith]

Looks great. Clean and pretty. Nice work!