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

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.30%. Comparing base (70faaa5) to head (65491b6).
⚠️ Report is 738 commits behind head on main.

Additional details and impacted files

@@           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           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[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!