Docs: add feature documentation for build.jobs

[agjohnson]

Author some documentation with some examples, common use cases, and some more description of the new feature.

[agjohnson]

This originally mentioned authoring guide content, but I'd still like to push more content into top-level, feature documentation, instead of tucked away in guides content.

We need to decide how we want to describe this as a product feature, we need something more user-friendly than calling it build.jobs. If someone asked me to describe it I'd call it something more like "build command hooks" or something.

Anyways, when I say feature documentation, I'm describing a top-level document "Build customization" or something that we would slide into the list of Read the Docs features on the front page.

[humitos]

We've talked a little about how to expose this to users in one of our planning meetings and we have some notes at https://trello.com/c/zuGW7ywZ/9-execute-arbitrary-commands#comment-60524f6b21f59534f53e33c7. In those notes, there are some examples about what users would like to do with this (e.g. doxygen, openapi/swagger, etc). It may be good to review those notes and expand with examples in the documentation guide.

[humitos]

I think it's fine to work in a document named "Build customization" as you mentioned. I did some research to find the common cases we were asked for and I found some of them that we could use in this document.

I wrote these notes as a potential structure this document could have --but I don't know how to write the document yet 😅 :

• explains that Read the Docs executes by default the common commands to build a regular Sphinx/MkDocs project
• expand by saying that this sometimes is not enough, and other commands may be required to install custom dependencies
• comment simple ways install these dependencies (python.install.requirements, build.apt_packages, etc)
• however, if installing dependencies is not enough, and arbitrary commands are required, build.jobs could be helpful here
• explain how to use build.jobs pointing to the documentation reference and show a very basic example
• show some useful known cases where build.jobs could be handy:
  • post_checkout: unshallow clone (Allow to disable shallow clone from the project's settings #5989)
  • pre_install: setuptools_scm (Setuptools_scm incorrect version and Conda environments  #8201)
  • post_install: pydoc-markdown (Allow custom run steps in .readthedocs.yml #8963)
  • pre_build: doxygen (https://stackoverflow.com/questions/36064976/using-doxygen-in-read-the-docs)
    • Command: doxygen
  • pre_build: sphinx linkcheck (https://www.writethedocs.org/guide/tools/testing/#link-testing)
    • Command: python -m sphinx -b linkcheck docs/ _build/linkcheck
  • pre_build: support for Jupyter Book (BREAKING, DOCS: Add readthedocs builds and deprecate pre-commit hook jupyter-book/jupyter-book#1711)

@agjohnson please, let me know if this is more or less aligned with what you have in mind.

[ericholscher]

Testing is another good one to cover. I think it makes sense to break these high-level goals out into their own guides, eg. Testing your documentation which could cover:

• Sphinx's doctest
• Linting with eg. vale (Setup vale linter bot #5876)
• Linkcheck probably
• running these commands in RTD

I think we already have a build process page, which should probably hold a lot of this proposed info and needs some updates: https://docs.readthedocs.io/en/latest/builds.html

I think Build customization is pretty generic, and I'd like to see more focused content solving common issues broken out into guides, I think. That seems like it would be easier to find, but at least having the content written somewhere is more important than how it's structured IMO.

I do think we should have a full guide covering all the various build.jobs configs, but also include longer use cases in topic-specific guides as well. I'm imagining build.jobs being a reference, but I'm not sure what the structure of that would be. Perhaps as part of the TOC that you proposed, in the Build process page?

[agjohnson]

I'd agree some of this should also be included in our build process documentation, and eventually we want some guides for specific use cases. I don't have a problem with minor examples in our feature documentation, these are low stakes and we can produce these fairly easily.

But, I'm mostly advocating for writing more top-level content that we can market first, perhaps focusing a bit on our SEO. This doc is especially important, as build customization is the primary place that users need to fiddle with RTD.

Guides are much more specific, and not as discoverable or translatable as generic content. We can always add guides as we go and find gaps in our documentation or user use-cases. It may help to accumulate solutions to user use cases, like how to test with Sphinx, but the initial missing piece is more generic than guide content.

I put down some more thoughts here, but general discoverability of our documentation is a significant (but very separate) issue:
https://github.com/readthedocs/meta/issues/7

@humitos what you're describing is indeed close to what I'm describing, and perhaps even a step or two further. I'd be happy to have any start to a doc like this, but agree we could use a bottom up approach to a doc like this. This is maybe one of the more important documents we should maintain, and the fact that our config file doc comes up in search results most frequently is maybe proof of that.

However, generally speaking, I think we need to balance our documentation out more and author narrative content rather than link to our config file documentation. I agree the config file doc works great as a reference doc, but it doesn't do a great job of guiding the user if they don't know what they need.

And it arguably shouldn't, it's a reference doc. This is where narrative or feature documentation would help guide the user more, and likely make SEO easier.

The one thing I'll add to your list, is that we should cover the build steps sequentially and with a bit more description of what happens before/after each step. This could be a replacement for some of the content in the build process doc. That doc needs some additional help to be useful though. But anyways, for non-core team it's probably not clear when these build hooks are executed and what native commands are executed in between:

[humitos]

I opened a PR at #9138 with an initial version of this. I think it covers the main aspects we discussed here and it could work as a starting point that we can improve over time when we find more use cases and more examples.

I left Eric's idea for testing outside this initial version. I think these particular cases can be covered in user guides as we talked. I mainly focused on having narrative content that walks the user through the default build process pointing them to specific config keys to improve their experience. Finally, if that's not enough, it points them to the "Build customization" page that explains how to use build.jobs more deeper.