Build: notes from output directory standardization

[humitos]

We discussed many good points while reviewing #9888 but we didn't apply them because they may require some extra research, work, and decisions. So, I'm writing them down here as simple notes to keep them in mind. If there are more details needed, you can go do that PR in particular and read the "Resolved conversations"

• Use an environment variable for output directory (e.g. $READTHEDOCS_OUTPUT pointing to .../_readthedocs/). Build: use environment variable $READTHEDOCS_OUTPUT to define output directory #9913
• Support multiple format files (PDF, HTMLZIP, ePub) Build: standardize output directory for artifacts #9888 (comment) and Multiple pdf files for single project #2045
  • Serve them individually
  • Serve them as a .zip file containing all the files for each format
• Do not fail the build for a particular format silently Build: standardize output directory for artifacts #9888 (comment)
• Continue thinking about executing sphinx-build commands from the cloned directory (instead of from the conf.py directory) Build: standardize output directory for artifacts #9888 (comment)
• Project.config_file should raise different exception for different issues Build: standardize output directory for artifacts #9888 (comment)
  • A project with multiple conf.py files without specifying which one to use, should explicitly fail the build
  • A project without a conf.py should not raise an exception and create a file for them
• Document that _readthedocs/<format> directories are cleanup immediately before running build.jobs.build commands Build: standardize output directory for artifacts #9888 (comment)
  • People wanting to add extra files there or modify its content, should use build.jobs.post_build
• We should update the DB instance always, not only when HTML built successfully Build: standardize output directory for artifacts #9888 (comment) and Build: upload artifacts atomically (support instant rollbacks) #9947

Related

• Build: standardize output directory for artifacts #9888
• Docs: explain how _readthedocs/<format> directories work, and add examples #9894
• Builder: remove PDF support for Sphinx<=1.6.1 #9886
• Build: use environment variable $READTHEDOCS_OUTPUT to define output directory #9913

[humitos]

I'm closing this issue because 90% of the points are already completed and the other ones have their own issues. We moved pretty quickly here and I'm happy with that 💪🏼