Document new build jobs #11900
Document new build jobs #11900
Conversation
docs/user/build-customization.rst
Outdated
| build.commands | ||
| ~~~~~~~~~~~~~~ |
There was a problem hiding this comment.
I would call this "Completely override the build process" as it is presented at the beginning of the page. Also, I'd use ---- for the section:
| build.commands | |
| ~~~~~~~~~~~~~~ | |
| Completely override the build process | |
| ----------------------------------------------------------- |
There was a problem hiding this comment.
I would avoid having a title with just build.commands since it doesn't communicate too much the users.
There was a problem hiding this comment.
I think this should under this section, but renamed it to "alternative syntax"
|
|
||
| Extend the build process | ||
| ------------------------ | ||
| Extend or override the build process |
There was a problem hiding this comment.
| Extend or override the build process | |
| Extend or partially override the build process |
There was a problem hiding this comment.
build.jobs allows for both, partial and complete override, the only difference with build.commands is the way it's done and the support for apt packages.
There was a problem hiding this comment.
I liked how the items above linked to the relevant sections previously.
I don't think we need to get into specifics of partially/full overriding in the section headings. In fact, I'd be clearer with both of these items/headings:
- Customize our standard build process
- Define a build process from scratch
That is, describe the effect to the end user more than technically describe what's happening in the build.
|
|
||
| Extend the build process | ||
| ------------------------ | ||
| Extend or override the build process |
There was a problem hiding this comment.
I liked how the items above linked to the relevant sections previously.
I don't think we need to get into specifics of partially/full overriding in the section headings. In fact, I'd be clearer with both of these items/headings:
- Customize our standard build process
- Define a build process from scratch
That is, describe the effect to the end user more than technically describe what's happening in the build.
| the ``create_environment``, ``install``, and ``build`` jobs will use the default commands for the selected tool, | ||
| otherwise, they will default to run nothing. |
There was a problem hiding this comment.
Can't do suggest for some reason 🤷
I'd make this two sentences.
...jobs will use the default commands for the selected tool.
If no tool configuration is specified, these jobs won't execute anything by default.
There was a problem hiding this comment.
probably because the PR was already merged :)
| You can access the search from the Read the Docs :term:`dashboard`, | ||
| or by using the :doc:`/server-side-search/api`. |
There was a problem hiding this comment.
If you are referring to the search view UI in the dashboard, that feels unrelated to documentation search and build configuration.
There was a problem hiding this comment.
this section was already in the document, but it refers to search support for all tools.
| - uv pip install -r requirements.txt | ||
| build: | ||
| html: | ||
| - uv run sphinx-build -T -b html docs $READTHEDOCS_OUTPUT/html |
There was a problem hiding this comment.
This is a nice improvement 👍
Ref https://github.com/readthedocs/readthedocs-ops/issues/1582
📚 Documentation previews 📚
docs): https://docs--11900.org.readthedocs.build/en/11900/dev): https://dev--11900.org.readthedocs.build/en/11900/