Docs: feature documentation for `build.jobs` #9138

humitos · 2022-04-25T15:17:26Z

The general idea of these changes is to walk the user through the build process
itself while recommending/suggesting how to interact with that step in
particular via the config file to extend its abilities.

Besides, link to a different page where it's explained "how to use hooks" to
customize the normal build process in case the regular build process is not enough.

Decisions made:

Update "Build process" page (build.rst) to describe what happens behind the
scenes in a general way
Link to config file keys on each step when makes sense a recommendation or a tip
Remove paragraph and sections that are not interesting for users (Docker
images and where to find them)
Move "default versions of dependencies" to its own page since they are not one
of the most important things users need to know about the build process immediately
Rename section "Build environment" to "Default environment variables" to make
it clearer and use the keyword environment variables that will provide more
search results
Remove the "example in code" section since it's useful for regular users and
it's harder to read than the steps themselves. I think it's more distractive
than useful now
Move "Build resources" below the build process itself since the most importat
part of this page is the build process ("Understanding what's going on")
Create a new page "Build customization" that explains how to extend the build
process via build.jobs by mentioning all the possible hooks. Besides, it
contains some common examples as a guide

I think this is a good starting point and I like the result. I'd like feedback about how to expand the introduction of build-customization.rst page, in particular, to give a more descriptive scenario without introducing a lot of paragraphs 😄

🤖 Rendered version:

builds https://docs--9138.org.readthedocs.build/en/9138/builds.html
build customization: https://docs--9138.org.readthedocs.build/en/9138/build-customization.html

Closes #9067

The general idea of these changes is to walk the user through the build process itself while recommending/suggesting how to interact with that step in particular via the config file to extend its abilities. Besides, link to a different page where it's explained "how to use hooks" to customize the normal build process in case the regular build process is not enough. Decisions made: - Update "Build process" page (`build.rst`) to describe what happens behind the scenes in a general way - Link to config file keys on each step when makes sense a recommendation or a tip - Remove paragraph and sections that are not interesting for users (Docker images and where to find them) - Move "default versions of dependencies" to its own page since they are not one of the most important things users need to know about the build process immediately - Rename section "Build environment" to "Default environment variables" to make it clearer and use the keyword _environment variables_ that will provide more search results - Remove the "example in code" section since it's useful for regular users and it's harder to read than the steps themselves. I think it's more distractive than useful now - Move "Build resources" below the build process itself since the most importat part of this page is the build process ("Understanding what's going on") - Create a new page "Build customization" that explains how to extend the build process via `build.jobs` by mentioning all the possible hooks. Besides, it contains some common examples as a guide

We don't want to expose the exact commands to the users in the documentation. Besides, using jobs from the beginning is easier to understand `build.jobs` config key later.

ericholscher

This is a great refactor! I'm excited to ship this, as it's a great improvement. I did a bunch of copyediting, so sorry for the noise. Overall this is wondeful.

I think the main thing we need to address is standardizing what we call build steps, since we seem to be all over the place there.

docs/user/builds.rst