Docs: Refactor downloadable docs

[ericholscher]

Refs #9746
Closes #9577

---

📚 Documentation previews 📚

• User's documentation (docs): https://docs--9768.org.readthedocs.build/en/9768/

• Developer's documentation (dev): https://dev--9768.org.readthedocs.build/en/9768/

[humitos]

When splitting content into explanation and how-to, shouldn't we link them each other somehow? I mean, as a user, after reading the explanation and I will be excited about offline formats and I'd want to know how to enable the in my project.

It works in the other direction too, I guess. Arriving at the "how-to" without knowing exactly what they are, I may be lost. So, a link back to the explanation in the first or second paragraph could work great here.

[humitos]

When splitting content into explanation and how-to, shouldn't we link them each other somehow? I mean, as a user, after reading the explanation and I will be excited about offline formats and I'd want to know how to enable the in my project.

I think this can be standardized in a simple way to start. Maybe just a .. seealso:: with some bullets and links at the end of the pages?

.. seealso::

  * :doc:`downloadable-documentation`

[benjaoming]

@humitos yup, definitely, we also used seealso:: in other Diátaxis refactors, although the text has varied a bit. I don't think we're far from arriving at some kind of template. I'm trying to compile generic inputs here: https://docs.google.com/document/d/1Ir8UvupznvAH4oF4-DEiXrILnEk2Lqsg4FrPDA-8uXA/edit#

[ericholscher]

@humitos yup, definitely, we also used seealso:: in other Diátaxis refactors, although the text has varied a bit. I don't think we're far from arriving at some kind of template. I'm trying to compile generic inputs here: https://docs.google.com/document/d/1Ir8UvupznvAH4oF4-DEiXrILnEk2Lqsg4FrPDA-8uXA/edit#

Strong agree on the seealso, I just ran out of energy last night when working on it 😆

[ericholscher]

Updates are ready for review 👍

[ericholscher]

@benjaoming Would love a review on this soon, so we can get it merged.

[benjaoming]

I have sync'ed branches, which worked fine.

Have just the one suggestion above to add some kind of explanation about the role of the documentation framework.

Otherwise, looks great, really nice to get started with this, as there are many additional things in the horizon. Noticing both custom build processes, but also suggestions to add DocSets support 👍