diff --git a/docs/user/build-customization.rst b/docs/user/build-customization.rst index dec4ab40a83..3fbd7dd478f 100644 --- a/docs/user/build-customization.rst +++ b/docs/user/build-customization.rst @@ -429,7 +429,10 @@ Take a look at the following example: Install dependencies with ``uv`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Projects managed with `uv `__ can install `uv` with asdf, +For a complete guide with multiple ``uv`` workflows and recommendations, +see :doc:`/guides/uv`. + +Projects managed with `uv `__ can install ``uv`` with asdf, and then rely on it to set up the environment and install the python project and its dependencies. Read the Docs' own build steps expect it by setting the ``UV_PROJECT_ENVIRONMENT`` variable, usually reducing the time taken to install compared to pip. @@ -457,8 +460,8 @@ If a ``uv.lock`` file exists it is respected. jobs: pre_create_environment: - asdf plugin add uv - - asdf install uv latest - - asdf global uv latest + - asdf install uv 0.10.6 + - asdf global uv 0.10.6 create_environment: - uv venv "${READTHEDOCS_VIRTUALENV_PATH}" install: diff --git a/docs/user/guides/build/index.rst b/docs/user/guides/build/index.rst index 797e6589d18..42b5355fbda 100644 --- a/docs/user/guides/build/index.rst +++ b/docs/user/guides/build/index.rst @@ -15,6 +15,9 @@ How-to guides: build process ⏩️ :doc:`Using custom environment variables ` Extra environment variables, for instance secrets, may be needed in the build process and can be defined from the project's :term:`dashboard`. +⏩️ :doc:`Using uv on Read the Docs ` + Use ``uv`` with lockfile-based or requirements-based workflows for your documentation builds. + ⏩️ :doc:`Managing versions automatically ` Automating your versioning on Read the Docs means you only have to handle your versioning logic in Git. Learn how to define rules to automate creation of new versions on Read the Docs, @@ -38,5 +41,6 @@ How-to guides: build process /guides/build/webhooks Configuring pull request builds Using custom environment variables + Using uv on Read the Docs Managing versions automatically Skip builds based on conditions diff --git a/docs/user/guides/uv.rst b/docs/user/guides/uv.rst new file mode 100644 index 00000000000..51043d3f0aa --- /dev/null +++ b/docs/user/guides/uv.rst @@ -0,0 +1,162 @@ +Using ``uv`` on Read the Docs +============================= + +`uv `__ can be used on Read the Docs to install documentation dependencies quickly. +You can use it as a full project manager with ``uv.lock``, +or as a faster installer for existing ``requirements.txt`` files. + +This guide shows recommended patterns for both Sphinx and MkDocs projects. + +.. contents:: Contents + :local: + :depth: 2 + +Recommended approach: ``uv`` project with ``uv.lock`` +------------------------------------------------------ + +For most projects, we recommend: + +* Defining docs dependencies in a ``docs`` dependency group in ``pyproject.toml``. +* Committing ``uv.lock`` to your repository. +* Using ``uv sync --frozen`` in Read the Docs builds. +* Pinning your ``uv`` version instead of using ``latest``. + +This gives you the most :term:`reproducible` setup and keeps local and hosted builds aligned. + +.. code-block:: yaml + :caption: .readthedocs.yaml + + version: 2 + + sphinx: + configuration: docs/conf.py + + build: + os: "ubuntu-24.04" + tools: + python: "3.13" + jobs: + pre_create_environment: + - asdf plugin add uv + - asdf install uv 0.10.6 + - asdf global uv 0.10.6 + create_environment: + - uv venv "$READTHEDOCS_VIRTUALENV_PATH" + install: + - UV_PROJECT_ENVIRONMENT="$READTHEDOCS_VIRTUALENV_PATH" uv sync --frozen --group docs + +.. note:: + + If your docs require optional dependencies, + add them with ``--extra `` or ``--all-extras`` in the ``uv sync`` command. + +Alternative: ``uv`` project without lock file enforcement +--------------------------------------------------------- + +If you do not commit ``uv.lock`` yet, +or if you intentionally want dependency updates during builds, +you can drop ``--frozen``: + +.. code-block:: yaml + :caption: .readthedocs.yaml + + version: 2 + + sphinx: + configuration: docs/conf.py + + build: + os: "ubuntu-24.04" + tools: + python: "3.13" + jobs: + pre_create_environment: + - asdf plugin add uv + - asdf install uv 0.10.6 + - asdf global uv 0.10.6 + create_environment: + - uv venv "$READTHEDOCS_VIRTUALENV_PATH" + install: + - UV_PROJECT_ENVIRONMENT="$READTHEDOCS_VIRTUALENV_PATH" uv sync --group docs + +This is easier to adopt quickly, +but it is less reproducible than using ``uv.lock`` with ``--frozen``. + +Alternative: use ``uv`` with ``requirements.txt`` +------------------------------------------------- + +If your project is not managed as a ``uv`` project, +you can still use ``uv`` as an installer for existing requirements files: + +.. code-block:: yaml + :caption: .readthedocs.yaml + + version: 2 + + sphinx: + configuration: docs/conf.py + + build: + os: "ubuntu-24.04" + tools: + python: "3.13" + jobs: + pre_create_environment: + - asdf plugin add uv + - asdf install uv 0.10.6 + - asdf global uv 0.10.6 + create_environment: + - uv venv "$READTHEDOCS_VIRTUALENV_PATH" + install: + - uv pip install --python "$READTHEDOCS_VIRTUALENV_PATH/bin/python" -r docs/requirements.txt + +.. tip:: + + If your build imports your package itself, + install it in the same step with ``uv pip install --python "$READTHEDOCS_VIRTUALENV_PATH/bin/python" .``. + +Using ``uv`` with MkDocs +------------------------ + +The same ``uv`` installation patterns work with MkDocs. +Only the tool-specific configuration changes: + +.. code-block:: yaml + :caption: .readthedocs.yaml + + version: 2 + + mkdocs: + configuration: mkdocs.yml + + build: + os: "ubuntu-24.04" + tools: + python: "3.13" + jobs: + pre_create_environment: + - asdf plugin add uv + - asdf install uv 0.10.6 + - asdf global uv 0.10.6 + create_environment: + - uv venv "$READTHEDOCS_VIRTUALENV_PATH" + install: + - UV_PROJECT_ENVIRONMENT="$READTHEDOCS_VIRTUALENV_PATH" uv sync --frozen --group docs + +Recommendations +--------------- + +* Pin ``build.os`` and ``build.tools.python`` in ``.readthedocs.yaml``. +* Pin your ``uv`` version in ``asdf install uv 0.10.6``. +* Prefer ``uv.lock`` and ``uv sync --frozen`` for reproducible builds. +* Keep docs-only dependencies in a dedicated ``docs`` group. +* Set ``UV_PROJECT_ENVIRONMENT`` inline on the command using ``uv sync``. + +.. seealso:: + + :doc:`/guides/reproducible-builds` + Recommendations for reproducible docs builds. + :doc:`/build-customization` + Learn more about the ``build.jobs`` customization model. + :doc:`/reference/environment-variables` + Reference for environment variables available in builds. diff --git a/docs/user/testing.rst b/docs/user/testing.rst new file mode 100644 index 00000000000..2fc8513e492 --- /dev/null +++ b/docs/user/testing.rst @@ -0,0 +1,220 @@ +Automating and Testing Documentation +==================================== + +Documentation is important to your users, +so you want to make sure it's always correct. +Read the Docs can automatically validate and test your documentation during each build, +catching issues before they reach production. + +This guide shows you how to integrate testing tools into your Read the Docs builds +using custom build jobs and dependencies. + +Overview +-------- + +Read the Docs builds can run custom validation commands as part of the build process. +You can integrate linting, code snippet validation, and link checking directly in ``.readthedocs.yaml``. +If a validation step fails, the entire build fails and the docs are not deployed. + +Vale: Prose and style linting +------------------------------ + +Vale checks for consistency in voice, tone, terminology, and style across your documentation. +Unlike generic linters, Vale understands documentation best practices and catches issues like passive voice overuse, inconsistent terminology, and style guide violations. + +**Setup** + +Create a ``.vale.ini`` file in your project root: + +.. code-block:: ini + + [*] + BasedOnStyles = Vale,Microsoft + StylesPath = styles + MinAlertLevel = warning + +Vale comes with built-in style guides (Vale, Microsoft, Google). You can also create custom style rules. + +**Integration in Read the Docs** + +Add Vale to your ``docs/requirements.txt``: + +.. code-block:: text + + vale==3.0.0 + +Then configure a custom build job in ``.readthedocs.yaml``: + +.. code-block:: yaml + + version: 2 + build: + os: ubuntu-22.04 + tools: + python: "3.11" + + python: + install: + - requirements: docs/requirements.txt + + jobs: + post_build: + - vale docs/ + +If Vale finds style issues, the build fails and displays the full report. You can configure which checks fail the build using alert levels in ``.vale.ini``: + +.. code-block:: ini + + [*] + MinAlertLevel = error + +This way, warnings don't fail the build but errors do. + +Doc Detective: Code snippet validation +--------------------------------------- + +Doc Detective automatically executes code snippets embedded in your documentation to ensure they actually work. +This is invaluable for keeping examples up-to-date as your product evolves. +It supports Python, JavaScript, Go, Bash, and other languages, catching broken examples and outdated API usage that would confuse users. + +**Setup** + +Create a ``doc-detective.json`` in your project root: + +.. code-block:: json + + { + "runTests": true, + "checkLinks": true, + "autoDetectLanguages": true, + "errorOnFail": true, + "ignorePatterns": ["node_modules", ".git"] + } + +Add test configurations for your language. Example for Python: + +.. code-block:: json + + { + "runTests": true, + "testRunnerConfig": { + "python": { + "install": ["pip install -r requirements.txt"], + "setup": "import sys; sys.path.insert(0, '.')" + } + } + } + +**Integration in Read the Docs** + +Add doc-detective to your ``docs/requirements.txt``: + +.. code-block:: text + + doc-detective==0.5.0 + +In code blocks, wrap examples with metadata comments: + + .. code-block:: python + + # doc-detective-test + result = 1 + 1 + assert result == 2 + +Configure the build in ``.readthedocs.yaml``: + +.. code-block:: yaml + + version: 2 + build: + os: ubuntu-22.04 + tools: + python: "3.11" + + python: + install: + - requirements: docs/requirements.txt + + jobs: + post_build: + - doc-detective execute + +If any code snippet fails, the build fails and shows which snippet broke and why. + +Sphinx build strictness +----------------------- + +For reStructuredText projects, Sphinx can catch structural and formatting issues automatically. +Configure Sphinx to treat warnings as errors, so broken cross-references and malformed directives fail the build immediately. + +**Setup in conf.py** + +.. code-block:: python + + import warnings + + warnings.filterwarnings("error", category=Warning) + +**Configuration in Read the Docs** + +Set ``fail_on_warning`` in ``.readthedocs.yaml``: + +.. code-block:: yaml + + version: 2 + build: + os: ubuntu-22.04 + tools: + python: "3.11" + + python: + install: + - requirements: docs/requirements.txt + + sphinx: + configuration: docs/conf.py + fail_on_warning: true + +This automatically fails the build if Sphinx encounters any warnings, including: + +* Broken internal references and ``.. automodule::`` directives +* Malformed RST syntax +* Missing or duplicate labels +* Unused footnotes and citations + +Complete example +---------------- + +Here's a complete ``.readthedocs.yaml`` with multiple validation steps: + +.. code-block:: yaml + + version: 2 + + build: + os: ubuntu-22.04 + tools: + python: "3.11" + + python: + install: + - requirements: docs/requirements.txt + + sphinx: + configuration: docs/conf.py + fail_on_warning: true + + jobs: + post_build: + - vale docs/ + - doc-detective execute + +When you push changes, Read the Docs will: + +1. Install your documentation dependencies +2. Build Sphinx and fail on any warnings +3. Run Vale for prose linting +4. Execute and validate all code snippets with Doc Detective +5. Only deploy if all steps pass + +This ensures your documentation is correct, complete, and ready for your users.