diff --git a/docs/user/build-customization.rst b/docs/user/build-customization.rst index 451ace04945..50bfabb14f3 100644 --- a/docs/user/build-customization.rst +++ b/docs/user/build-customization.rst @@ -4,21 +4,21 @@ Build process customization Read the Docs has a :doc:`well-defined build process ` that works for many projects. We also allow customization of builds in two ways: -`Extend the build process`_ - Keep using the default build process, - adding your own commands. +Extend or partially override the build process + Keep using the default commands for MkDocs or Sphinx, + but extend or override the ones you need. -`Override the build process`_ - This option gives you *full control* over your build. - Read the Docs supports any tool that generates HTML. +Completely override the build process + This option gives you *full control* over your build. + Read the Docs supports any tool that generates HTML. -Extend the build process ------------------------- +Extend or override the build process +------------------------------------ -In the normal build process, -the pre-defined jobs ``checkout``, ``system_dependencies``, ``create_environment``, ``install``, ``build`` and ``upload`` are executed. -Read the Docs also exposes these jobs, -which allows you to customize the build process by adding shell commands. +In the normal build process, the pre-defined jobs ``checkout``, ``system_dependencies``, and ``upload`` are executed. +If you define a :ref:`config-file/v2:sphinx` or :ref:`config-file/v2:mkdocs` configuration, +the ``create_environment``, ``install``, and ``build`` jobs will use the default commands for the selected tool, +otherwise, they will default to run nothing. The jobs where users can customize our default build process are: @@ -33,26 +33,32 @@ The jobs where users can customize our default build process are: * - System dependencies - ``pre_system_dependencies``, ``post_system_dependencies`` * - Create environment - - ``pre_create_environment``, ``post_create_environment`` + - ``pre_create_environment``, ``create_environment``, ``post_create_environment`` * - Install - - ``pre_install``, ``post_install`` + - ``pre_install``, ``install``, ``post_install`` * - Build - - ``pre_build``, ``post_build`` + - ``pre_build``, ``build``, ``post_build`` * - Upload - No customizable jobs currently .. note:: - The pre-defined jobs (``checkout``, ``system_dependencies``, etc) cannot be overridden or skipped. - You can fully customize things in :ref:`build-customization:override the build process`. + Any other pre-defined jobs (``checkout``, ``system_dependencies``, ``upload``) cannot be overridden or skipped. -These jobs are defined using the :doc:`/config-file/v2` with the :ref:`config-file/v2:build.jobs` key. -This example configuration defines commands to be executed *before* installing and *after* the build has finished: +These jobs are defined using the :doc:`configuration file ` with the :ref:`config-file/v2:build.jobs` key. +This example configuration defines commands to be executed *before* installing and *after* the build has finished, +and also overrides the default build command for the ``htmlzip`` format, while keeping the default commands for the ``html`` and ``pdf`` formats: .. code-block:: yaml :caption: .readthedocs.yaml version: 2 + formats: [htmlzip, pdf] + sphinx: + configuration: docs/conf.py + python: + install: + - requirements: docs/requirements.txt build: os: "ubuntu-22.04" tools: @@ -60,33 +66,117 @@ This example configuration defines commands to be executed *before* installing a jobs: pre_install: - bash ./scripts/pre_install.sh + build: + # The default commands for generating the HTML and pdf formats will still run. + htmlzip: + - echo "Override default build command for htmlzip format" + - mkdir -p $READTHEDOCS_OUTPUT/htmlzip/ + - echo "Hello, world!" > $READTHEDOCS_OUTPUT/htmlzip/index.zip post_build: - curl -X POST \ -F "project=${READTHEDOCS_PROJECT}" \ -F "version=${READTHEDOCS_VERSION}" https://example.com/webhooks/readthedocs/ +Features and limitations +~~~~~~~~~~~~~~~~~~~~~~~~ -User-defined job limitations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -* The current working directory is at the root of your project's cloned repository -* Environment variables are expanded for each individual command (see :doc:`/reference/environment-variables`) -* Each command is executed in a new shell process, so modifications done to the shell environment do not persist between commands +* The current working directory is at the root of your project's cloned repository. +* Environment variables are expanded for each individual command (see :doc:`/reference/environment-variables`). +* Each command is executed in a new shell process, so modifications done to the shell environment do not persist between commands. * Any command returning non-zero exit code will cause the build to fail immediately - (note there is a special exit code to `cancel the build `_) -* ``build.os`` and ``build.tools`` are required when using ``build.jobs`` + (note there is a special exit code to `cancel the build `_). +* ``build.os`` and ``build.tools`` are required when using ``build.jobs``. +* If the :ref:`config-file/v2:sphinx` or :ref:`config-file/v2:mkdocs` configuration is defined, + the ``create_environment``, ``install``, and ``build`` jobs will use the default commands for the selected tool. +* If neither of the :ref:`config-file/v2:sphinx` or :ref:`config-file/v2:mkdocs` configurations are defined, + the ``create_environment``, ``install``, and ``build`` jobs will default to run nothing, + giving you full control over the build process. + +Where to put files +~~~~~~~~~~~~~~~~~~ + +It is your responsibility to generate HTML and other formats of your documentation when overriding the steps from :ref:`config-file/v2:build.jobs.build`. +The contents of the ``$READTHEDOCS_OUTPUT//`` directory will be hosted as part of your documentation. + +We store the the base folder name ``_readthedocs/`` in the environment variable ``$READTHEDOCS_OUTPUT`` and encourage that you use this to generate paths. + +Supported :ref:`formats ` are published if they exist in the following directories: + +* ``$READTHEDOCS_OUTPUT/html/`` (required) +* ``$READTHEDOCS_OUTPUT/htmlzip/`` +* ``$READTHEDOCS_OUTPUT/pdf/`` +* ``$READTHEDOCS_OUTPUT/epub/`` +.. note:: -``build.jobs`` examples -~~~~~~~~~~~~~~~~~~~~~~~ + Remember to create the folders before adding content to them. + You can ensure that the output folder exists by adding the following command: + + .. code-block:: console + + mkdir -p $READTHEDOCS_OUTPUT/html/ + +Search support +~~~~~~~~~~~~~~ + +Read the Docs will automatically index the content of all your HTML files, +respecting the :ref:`search ` option. + +You can access the search from the Read the Docs :term:`dashboard`, +or by using the :doc:`/server-side-search/api`. + +.. note:: + + In order for Read the Docs to index your HTML files correctly, + they should follow the conventions described at :doc:`rtd-dev:search-integration`. + +Alternative syntax +~~~~~~~~~~~~~~~~~~ + +Alternatively, you can use the :ref:`config-file/v2:build.commands` key to completely override the build process. + +.. code-block:: yaml + :caption: .readthedocs.yaml + + version: 2 + build: + os: "ubuntu-22.04" + tools: + python: "3.10" + commands: + - pip install pelican + - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/ + +But we recommend using :ref:`config-file/v2:build.jobs` instead: + +.. code-block:: yaml + :caption: .readthedocs.yaml + + version: 2 + build: + os: "ubuntu-22.04" + tools: + python: "3.10" + jobs: + install: + - pip install pelican + build: + html: + - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/ + +``build.jobs`` offers the same functionality as ``build.commands``, +but in a more structured way that allows you to define different commands for each format, +while also supporting installing system dependencies via ``build.apt_packages``. + +Examples +-------- We've included some common examples where using :ref:`config-file/v2:build.jobs` will be useful. These examples may require some adaptation for each projects' use case, we recommend you use them as a starting point. - Unshallow git clone -^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~ Read the Docs does not perform a full clone in the ``checkout`` job in order to reduce network data and speed up the build process. Instead, it performs a `shallow clone `_ and only fetches the branch or tag that you are building documentation for. @@ -123,7 +213,7 @@ If your build also relies on the contents of other branches, it may also be nece Cancel build based on a condition -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When a command exits with code ``183``, Read the Docs will cancel the build immediately. @@ -187,7 +277,7 @@ This other example shows how to cancel a build if the commit message contains `` Generate documentation from annotated sources with Doxygen -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It's possible to run Doxygen as part of the build process to generate documentation from annotated sources: @@ -207,7 +297,7 @@ It's possible to run Doxygen as part of the build process to generate documentat Use MkDocs extensions with extra required steps -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are some MkDocs extensions that require specific commands to be run to generate extra pages before performing the build. For example, `pydoc-markdown `_ @@ -216,6 +306,8 @@ For example, `pydoc-markdown :caption: .readthedocs.yaml version: 2 + mkdocs: + configuration: mkdocs.yml build: os: "ubuntu-20.04" tools: @@ -226,7 +318,7 @@ For example, `pydoc-markdown Avoid having a dirty Git index -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Read the Docs needs to modify some files before performing the build to be able to integrate with some of its features. Because of this reason, it could happen the Git index gets dirty (it will detect modified files). @@ -248,7 +340,7 @@ In that case, the Git index can be updated to ignore the files that Read the Doc Perform a check for broken links -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sphinx comes with a `linkcheck `_ builder that checks for broken external links included in the project's documentation. This helps ensure that all external links are still valid and readers aren't linked to non-existent pages. @@ -268,7 +360,7 @@ This helps ensure that all external links are still valid and readers aren't lin Support Git LFS (Large File Storage) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In case the repository contains large files that are tracked with Git LFS, there are some extra steps required to be able to download their content. @@ -301,7 +393,7 @@ It's possible to use ``post_checkout`` user-defined job for this. Install Node.js dependencies -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It's possible to install Node.js together with the required dependencies by using :term:`user-defined build jobs`. To setup it, you need to define the version of Node.js to use and install the dependencies by using ``build.jobs.post_install``: @@ -324,7 +416,7 @@ To setup it, you need to define the version of Node.js to use and install the de Install dependencies with Poetry -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Projects managed with `Poetry `__, can use the ``post_create_environment`` user-defined job to use Poetry for installing Python dependencies. @@ -341,11 +433,10 @@ Take a look at the following example: tools: python: "3.10" jobs: - post_create_environment: + post_install: # Install poetry # https://python-poetry.org/docs/#installing-manually - pip install poetry - post_install: # Install dependencies with 'docs' dependency group # https://python-poetry.org/docs/managing-dependencies/#dependency-groups # VIRTUAL_ENV needs to be set manually for now. @@ -357,7 +448,7 @@ Take a look at the following example: Install dependencies with ``uv`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Projects can use `uv `__, to install Python dependencies, usually reducing the time taken to install compared to pip. @@ -370,20 +461,25 @@ Take a look at the following example: version: 2 build: - os: "ubuntu-22.04" - tools: - python: "3.10" - commands: - - asdf plugin add uv - - asdf install uv latest - - asdf global uv latest - - uv sync --extra docs --frozen - - uv run -m sphinx -T -b html -d docs/_build/doctrees -D language=en docs $READTHEDOCS_OUTPUT/html + os: ubuntu-24.04 + tools: + python: "3.13" + jobs: + create_environment: + - asdf plugin add uv + - asdf install uv latest + - asdf global uv latest + - uv venv + install: + - uv pip install -r requirements.txt + build: + html: + - uv run sphinx-build -T -b html docs $READTHEDOCS_OUTPUT/html MkDocs projects could use ``NO_COLOR=1 uv run mkdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html`` instead. Update Conda version -^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~ Projects using Conda may need to install the latest available version of Conda. This can be done by using the ``pre_create_environment`` user-defined job to update Conda @@ -404,75 +500,14 @@ Take a look at the following example: pre_create_environment: - conda update --yes --quiet --name=base --channel=defaults conda + sphinx: + configuration: docs/conf.py + conda: environment: environment.yml - -.. _build_commands_introduction: - -Override the build process --------------------------- - -.. note:: - - We are using :ref:`our new addons integration ` - on projects using ``build.commands``. - `This will become the default soon `_, - but has some slight differences from our previous flyout. - -If your project requires full control of the build process, -and :ref:`extending the build process ` is not enough, -all the commands executed during builds can be overridden using the :ref:`config-file/v2:build.commands`. - -As Read the Docs does not have control over the build process, -you are responsible for running all the commands required to install requirements and build your project. - -Where to put files -~~~~~~~~~~~~~~~~~~ - -It is your responsibility to generate HTML and other formats of your documentation using :ref:`config-file/v2:build.commands`. -The contents of the ``$READTHEDOCS_OUTPUT//`` directory will be hosted as part of your documentation. - -We store the the base folder name ``_readthedocs/`` in the environment variable ``$READTHEDOCS_OUTPUT`` and encourage that you use this to generate paths. - -Supported :ref:`formats ` are published if they exist in the following directories: - -* ``$READTHEDOCS_OUTPUT/html/`` (required) -* ``$READTHEDOCS_OUTPUT/htmlzip/`` -* ``$READTHEDOCS_OUTPUT/pdf/`` -* ``$READTHEDOCS_OUTPUT/epub/`` - -.. note:: - - Remember to create the folders before adding content to them. - You can ensure that the output folder exists by adding the following command: - - .. code-block:: console - - mkdir -p $READTHEDOCS_OUTPUT/html/ - -Search support -~~~~~~~~~~~~~~ - -Read the Docs will automatically index the content of all your HTML files, -respecting the :ref:`search ` option. - -You can access the search from the Read the Docs :term:`dashboard`, -or by using the :doc:`/server-side-search/api`. - -.. note:: - - In order for Read the Docs to index your HTML files correctly, - they should follow the conventions described at :doc:`rtd-dev:search-integration`. - -``build.commands`` examples -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This section contains examples that showcase what is possible with :ref:`config-file/v2:build.commands`. -Note that you may need to modify and adapt these examples depending on your needs. - -Pelican -^^^^^^^ +Using Pelican +~~~~~~~~~~~~~ `Pelican `__ is a well-known static site generator that's commonly used for blogs and landing pages. If you are building your project with Pelican you could use a configuration file similar to the following: @@ -485,13 +520,16 @@ If you are building your project with Pelican you could use a configuration file os: "ubuntu-22.04" tools: python: "3.10" - commands: - - pip install pelican[markdown] - - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/ + jobs: + install: + - pip install pelican[markdown] + build: + html: + - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/ -Docsify -^^^^^^^ +Using Docsify +~~~~~~~~~~~~~ `Docsify `__ generates documentation websites on the fly, without the need to build static HTML. These projects can be built using a configuration file like this: @@ -502,14 +540,14 @@ These projects can be built using a configuration file like this: version: 2 build: os: "ubuntu-22.04" - tools: - nodejs: "16" - commands: - - mkdir --parents $READTHEDOCS_OUTPUT/html/ - - cp --recursive docs/* $READTHEDOCS_OUTPUT/html/ + jobs: + build: + html: + - mkdir --parents $READTHEDOCS_OUTPUT/html/ + - cp --recursive docs/* $READTHEDOCS_OUTPUT/html/ -Asciidoc -^^^^^^^^ +Using Asciidoc +~~~~~~~~~~~~~~ `Asciidoctor `__ is a fast processor for converting and generating documentation from AsciiDoc source. The Asciidoctor toolchain includes `Asciidoctor.js `__ which you can use with custom build commands. @@ -523,6 +561,9 @@ Here is an example configuration file: os: "ubuntu-22.04" tools: nodejs: "20" - commands: - - npm install -g asciidoctor - - asciidoctor -D $READTHEDOCS_OUTPUT/html index.asciidoc + jobs: + install: + - npm install -g asciidoctor + build: + html: + - asciidoctor -D $READTHEDOCS_OUTPUT/html index.asciidoc diff --git a/docs/user/builds.rst b/docs/user/builds.rst index 2853fe160aa..f7e039cad40 100644 --- a/docs/user/builds.rst +++ b/docs/user/builds.rst @@ -39,6 +39,10 @@ The build process includes the following jobs: Depending on what's defined by the project, a :term:`virtualenv` or a :ref:`conda environment ` will be used. + .. note:: + + This step is only executed if the :ref:`config-file/v2:sphinx` or :ref:`config-file/v2:mkdocs` keys are defined. + :install: Installs :doc:`default and project dependencies `. @@ -49,7 +53,11 @@ The build process includes the following jobs: .. tip:: - We strongly recommend :doc:`pinning all the versions ` required to build the documentation to avoid unexpected build errors. + We strongly recommend :doc:`pinning all the versions ` required to build the documentation to avoid unexpected build errors. + + .. note:: + + This step is only executed if the :ref:`config-file/v2:sphinx` or :ref:`config-file/v2:mkdocs` keys are defined. :build: diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst index 30ee7bff304..46d241709eb 100644 --- a/docs/user/config-file/v2.rst +++ b/docs/user/config-file/v2.rst @@ -419,7 +419,7 @@ We don't currently support PPA's or other custom repositories. build.jobs `````````` -Commands to be run before or after a Read the Docs :term:`pre-defined build jobs`. +Commands to be run before or after a Read the Docs :term:`pre-defined build jobs`, or to override a specific job. This allows you to run custom commands at a particular moment in the build process. See :doc:`/build-customization` for more details. @@ -441,33 +441,80 @@ See :doc:`/build-customization` for more details. .. note:: - Each key under ``build.jobs`` must be a list of strings. + Each build step consists of a list of commands to be executed. ``build.os`` and ``build.tools`` are also required to use ``build.jobs``. +.. note:: + + If the :ref:`config-file/v2:sphinx` or :ref:`config-file/v2:mkdocs` keys are present in the configuration file, + the default steps for each tool will be executed for the ``create_environment``, ``install``, and ``build`` steps. + You can override any of these steps, but be aware that some steps may depend on others, + for example, the default ``install`` and ``build`` steps depend on the ``create_environment`` step creating the Python virtual environment in a specific directory. + + If neither of the ``sphinx`` or ``mkdocs`` keys are present in the configuration file, + only the specified ``build.tools`` and ``build.apt_packages`` will be installed, + you will in charge of generating the documentation in the :ref:`$READTHEDOCS_OUTPUT ` directory. :Type: ``dict`` :Allowed keys: ``post_checkout``, ``pre_system_dependencies``, ``post_system_dependencies``, - ``pre_create_environment``, ``post_create_environment``, ``pre_install``, ``post_install``, - ``pre_build``, ``post_build`` + ``pre_create_environment``, ``create_environment``, ``post_create_environment``, ``pre_install``, ``post_install``, + ``pre_build``, ``build``, ``post_build`` :Required: ``false`` :Default: ``{}`` +build.jobs.build +```````````````` + +Commands to override the default build process. +When running builds from pull requests, only the ``html`` step will be executed. + +.. code-block:: yaml + + version: 2 + + formats: [pdf, epub] + build: + os: ubuntu-24.04 + tools: + python: "3.13" + jobs: + create_environment: + - echo "Preparing environment" + install: + - echo "Installing dependencies" + build: + html: + - echo "Building HTML" + - mkdir -p $READTHEDOCS_OUTPUT/html/ + - echo "Hello world!" > $READTHEDOCS_OUTPUT/html/index.html + pdf: + - echo "Building PDF" + - mkdir -p $READTHEDOCS_OUTPUT/pdf/ + - echo "Hello world!" > $READTHEDOCS_OUTPUT/pdf/index.pdf + epub: + - echo "Building ePub" + - mkdir -p $READTHEDOCS_OUTPUT/epub/ + - echo "Hello world!" > $READTHEDOCS_OUTPUT/epub/index.epub + +:Type: ``dict`` +:Allowed keys: ``html``, ``pdf``, ``epub``, ``htmlzip`` +:Required: ``false`` +:Default: ``{}`` + +.. note:: + + If any of the ``pdf``, ``epub``, or ``htmlzip`` steps are overridden, + they should be included in the :ref:`config-file/v2:formats` list. + +.. note:: + + For each format, you need to generate their output in the :ref:`$READTHEDOCS_OUTPUT ` directory. build.commands `````````````` Specify a list of commands that Read the Docs will run on the build process. When ``build.commands`` is used, none of the :term:`pre-defined build jobs` will be executed. -(see :doc:`/build-customization` for more details). -This allows you to run custom commands and control the build process completely. -The ``$READTHEDOCS_OUTPUT/html`` directory will be uploaded and hosted by Read the Docs. - -.. note:: - - We are using :ref:`our new addons integration ` - on projects using ``build.commands``. - `This will become the default soon `_, - but has some slight differences from our previous flyout. .. code-block:: yaml @@ -481,6 +528,28 @@ The ``$READTHEDOCS_OUTPUT/html`` directory will be uploaded and hosted by Read t - pip install pelican - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/ +But we recommend using :ref:`config-file/v2:build.jobs` instead: + +.. code-block:: yaml + :caption: .readthedocs.yaml + + version: 2 + build: + os: "ubuntu-22.04" + tools: + python: "3.10" + jobs: + install: + - pip install pelican + build: + html: + - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/ + +``build.jobs`` offers the same functionality as ``build.commands``, +but in a more structured way that allows you to define different commands for each format, +while also supporting installing system dependencies via ``build.apt_packages``. +See :doc:`/build-customization` for more details. + .. note:: ``build.os`` and ``build.tools`` are also required when using ``build.commands``. diff --git a/docs/user/intro/docusaurus.rst b/docs/user/intro/docusaurus.rst index 88c82d8cbce..c89d479ad85 100644 --- a/docs/user/intro/docusaurus.rst +++ b/docs/user/intro/docusaurus.rst @@ -7,7 +7,7 @@ Docusarus `Docusaurus`_ is a static-site generator that builds a single-page application with fast client-side navigation and out-of-the-box documentation features. Minimal configuration required to build a Docusaurus project on Read the Docs looks like this, -specifying a nodejs toolchain on Ubuntu, using multiple :ref:`build ` commands to install the requirements, +specifying a nodejs toolchain on Ubuntu, using multiple :ref:`build ` jobs to install the requirements, build the site, and copy the output to $READTHEDOCS_OUTPUT: .. code-block:: yaml @@ -18,18 +18,20 @@ build the site, and copy the output to $READTHEDOCS_OUTPUT: os: "ubuntu-22.04" tools: nodejs: "18" - commands: + jobs: # "docs/" was created following the Docusaurus tutorial: # npx create-docusaurus@latest docs classic # but you can just use your existing Docusaurus site - # - # Install Docusaurus dependencies - - cd docs/ && npm install - # Build the site - - cd docs/ && npm run build - # Copy generated files into Read the Docs directory - - mkdir --parents $READTHEDOCS_OUTPUT/html/ - - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/ + install: + # Install Docusaurus dependencies + - cd docs/ && npm install + build: + html: + # Build the site + - cd docs/ && npm run build + # Copy generated files into Read the Docs directory + - mkdir --parents $READTHEDOCS_OUTPUT/html/ + - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/ .. _Docusaurus: https://docusaurus.io/ diff --git a/docs/user/intro/mdbook.rst b/docs/user/intro/mdbook.rst index 71927cb29eb..890b5f79a21 100644 --- a/docs/user/intro/mdbook.rst +++ b/docs/user/intro/mdbook.rst @@ -17,11 +17,14 @@ Minimal configuration is required to build an existing mdBook project on Read th os: ubuntu-lts-latest tools: rust: latest - commands: + jobs: + install: - cargo install mdbook - # For an example book.. - # - mdbook init docs - - mdbook build docs --dest-dir $READTHEDOCS_OUTPUT/html + build: + html: + # For an example book.. + # - mdbook init docs + - mdbook build docs --dest-dir $READTHEDOCS_OUTPUT/html .. _mdBook: https://rust-lang.github.io/mdBook/