Refresh documentation

[gadomski]

There's a few issues (#751, #552, etc) about better docs. This is a tracking issue for updating the docs. Here's my recommendations:

• Switch to mkdocs-material, as reStructuredText is losing (has lost) to Markdown and mkdocs documentation (in this author's opinion) is easier to maintain over the long term
• Switch to pre-rendered notebooks (e.g. https://github.com/gadomski/antimeridian/blob/main/docs/comparison.ipynb) and don't render the notebooks on each build. This makes our doc build times faster
• (maybe) Switch to self-hosting docs via Github Pages instead of readthedocs (removes ads). @gadomski can help w/ this, setting up a redirect from readthedocs to here isn't too bad
• Do a general rewrite, as the docs were written a long time ago and there's been a lot of features bolted on since then

[jsignell]

Yes! I am looking at https://github.com/stac-utils/stac-fastapi/tree/main/docs and I particularly love how you can just inject the README and CHANGELOG into the docs so seamlessly.

I think it would be good to think holistically about the role of these docs (especially the notebooks) vs stac-wide docs (in particular tutorials: https://stacspec.org/en/tutorials/) , and the pystac docs.

I think my preference would be to include fewer long-form docs and focus on good API docs and possibly more "How to" or "cookbook" style docs that show you how to do one little thing and are easy for search indexes to surface (or I guess chatbots to digest 🙄 )

[gadomski]

I think my preference would be to include fewer long-form docs and focus on good API docs and possibly more "How to" or "cookbook" style docs that show you how to do one little thing and are easy for search indexes to surface (or I guess chatbots to digest 🙄 )

chatbots 🙃 ... but yes very much agreed. Especially as we continually build a "bigger than one repo" ecosystem.

[jsignell]

Ok this sounds great! Let's try to have a mini docs sprint or something - maybe on Friday (2025-02-07) or next week!