Docs: explain how `_readthedocs/<format>` directories work, and add examples

[humitos]

trafficstars

Once #9888 gets merged, we need to expand our documentation to explain how these directories work.

• [x] explain the basics about these directories and its limitations (e.g. one and only one file for non-html formats)
• [ ] show how to output non-html formats when using build.commands
• [ ] add use case for build.jobs.post_build (a potential good example: use staticrypt -- https://github.com/2i2c-org/team-compass/pull/585)
• [ ] example to build non-html formats on MkDocs via a plugin and outputting the artifacts on the right _readthedocs/ folder
• [ ] example that uses a different PDF (SimplePDF, rinohtype, rst2pdf) / HTMLZip (Zundler) build for Sphinx

[benjaoming]

There is a new documentation page in docs/user/reference/environment-variables.rst

[ericholscher]

I think we did this? https://docs.readthedocs.io/en/stable/build-customization.html#where-to-put-files

[humitos]

@ericholscher that was the initial work, yeah. However, we need to explain $READTHEDOCS_OUTPUT variable and create all the examples I mentioned in the description into test-builds and show them in the documentation. I'm happy to remove this off of my plate if that helps to move forward faster here and collaborate doing a review.

[agjohnson]

I think the second task above is close already, we have some examples in the documentation already. Though we don't have anything mentioning PDF/etc, if we think that is strictly necessary.

I would say one improvement to these docs would be moving the content for the build directories outside of build.commands specific sections. These directories are usable outside build.commands and we probably don't want to imply you need build.command to use these paths.

But with that, I think we can close this issue -- unless we have the energy for this content.

The other examples are nice to have, but not strictly necessary for a user to understand the path usage. They are more guides for how to use other tools then they are examples of using the output paths.

[humitos]

This is content that I'd eventually like to have. I haven't had the energy to write it down quickly and also to prioritize. I'd keep it open and mark it as low priority.

[ericholscher]

Next steps here are just better explaining how this functionality works in the docs. Current copy is here: https://docs.readthedocs.io/en/stable/build-customization.html#where-to-put-files