readthedocs · humitos · Jun 2, 2022 · Apr 27, 2022 · May 23, 2022 · May 23, 2022
@@ -4,7 +4,13 @@ Build customization
 Read the Docs has a :doc:`well-defined build process <builds>` that works for many projects,
 but we offer additional customization to support more uses of our platform.
 This page explains how to extend the build process using :term:`user-defined build jobs` to execute custom commands,
-and also how to :ref:`override the build process completely <build-customization:override the build process completely>`.
+and also how to override the build process completely:
+
+`Extend the build process`_
+    If you are using Sphinx or Mkdocs and need to execute additional commands.
+
+`Override the build process`_
+    If you want full control over your build or are not using Sphinx or Mkdocs.
 
 
 Extend the build process
@@ -42,7 +48,8 @@ These jobs can be declared by using a :doc:`/config-file/index` with the :ref:`c
 Let's say the project requires commands to be executed *before* installing any dependency into the Python environment and *after* the build has finished.
 In that case, a config file similar to this one can be used:
 
-.. code:: yaml
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
 
    version: 2
    build:
@@ -82,7 +89,8 @@ Read the Docs does not perform a full clone on ``checkout`` job to reduce networ
 Because of this, extensions that depend on the full Git history will fail.
 To avoid this, it's possible to unshallow the clone done by Read the Docs:
 
-.. code:: yaml
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
 
    version: 2
    build:
@@ -99,7 +107,8 @@ 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:
 
-.. code:: yaml
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
 
    version: 2
    build:
@@ -119,7 +128,8 @@ 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 <http://niklasrosenstein.github.io/pydoc-markdown/>`_
 
-.. code:: yaml
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
 
    version: 2
    build:
@@ -140,7 +150,8 @@ In case this happens and the project is using any kind of extension that generat
 this could cause an invalid version number to be generated.
 In that case, the Git index can be updated to ignore the files that Read the Docs has modified.
 
-.. code:: yaml
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
 
    version: 2
    build:
@@ -159,7 +170,8 @@ Sphinx comes with a `linkcheck <https://www.sphinx-doc.org/en/master/usage/build
 This helps ensure that all external links are still valid and readers aren't linked to non-existent pages.
 
 
-.. code:: yaml
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
 
    version: 2
    build:
@@ -178,7 +190,8 @@ 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.
 It's possible to use ``post_checkout`` user-defined job for this.
 
-.. code:: yaml
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
 
    version: 2
    build:
@@ -209,7 +222,8 @@ 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``:
 
-.. code:: yaml
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
 
    version: 2
    build:
@@ -225,23 +239,26 @@ To setup it, you need to define the version of Node.js to use and install the de
          - npm install -g jsdoc
 
 
-Override the build process completely
--------------------------------------
+Override the build process
+--------------------------
 
 .. warning::
 
    This feature is in a *beta phase* and could suffer incompatible changes or even removed completely in the near feature.
-   It does not yet support some of the Read the Docs' integrations like the :term:`flyout menu`, search and ads.
-   However, integrating all of them is part of the plan.
-   Use it under your own responsibility.
+   It does not yet support some of the Read the Docs' features like the :term:`flyout menu`, search and ads.
+   However, we do plan to support these features in the future.
+   Use this under your own risk.
 
 
-When :ref:`extending the build process <build-customization:extend the build process>` is not enough for a particular use case,
-all the default commands can be overwritten to execute only the commands defined by the project on its config file.
-This can be achieve by using :ref:`config-file/v2:build.commands` key as shown in the following example building a `Pelican <https://blog.getpelican.com/>`_ site:
+If your project requires full control of the build process,
+and :ref:`extending the build process <build-customization:extend the build process>` is not enough,
+all the commands executed during builds can be overridden using the :ref:`config-file/v2:build.commands` configuration file key.
 
+For example, if your project uses `Pelican <https://blog.getpelican.com/>`_ instead of Sphinx for it's documentation,
+your project could use the following configuration file:
 
-.. code:: yaml
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
 
    version: 2
    build:
@@ -250,9 +267,9 @@ This can be achieve by using :ref:`config-file/v2:build.commands` key as shown i
        python: "3.10"
      commands:
        - pip install pelican[markdown]
-       - pelican --settings docs/pelicanconf.py --output output/ docs/
+       - pelican --settings docs/pelicanconf.py --output _readthedocs/html/ docs/
 
 
 As Read the Docs does not have control over the build process,
-you are responsible to run all the commands required to install the requirements and build the documentation properly.
-Once the build process finishes, the ``output/`` folder will be hosted.
+you are responsible for running all the commands required to install requirements and build the documentation properly.
+Once the build process finishes, the ``_readthedocs/html/`` folder will be hosted.
@@ -473,7 +473,7 @@ 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 ``output/`` directory (relative to the checkout's path) will be uploaded and hosted by Read the Docs.
+The ``_readthedocs/html`` directory (relative to the checkout's path) will be uploaded and hosted by Read the Docs.
 
 .. warning::
 
@@ -492,7 +492,7 @@ The ``output/`` directory (relative to the checkout's path) will be uploaded and
        python: "3.10"
      commands:
        - pip install pelican
-       - pelican --settings docs/pelicanconf.py --output output/ docs/
+       - pelican --settings docs/pelicanconf.py --output _readthedocs/html/ docs/
 
 .. note::
 

@@ -0,0 +1,31 @@
+# Generated by Django 3.2.13 on 2022-05-30 10:24
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("builds", "0043_add_cancelled_state"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="version",
+            name="documentation_type",
+            field=models.CharField(
+                choices=[
+                    ("sphinx", "Sphinx Html"),
+                    ("mkdocs", "Mkdocs"),
+                    ("sphinx_htmldir", "Sphinx HtmlDir"),
+                    ("sphinx_singlehtml", "Sphinx Single Page HTML"),
+                    ("mkdocs_html", "Mkdocs Html Pages"),
+                    ("generic", "Generic"),
+                ],
+                default="sphinx",
+                help_text="Type of documentation the version was built with.",
+                max_length=20,
+                verbose_name="Documentation type",
+            ),
+        ),
+    ]
@@ -11,6 +11,7 @@
 from django.conf import settings
 
 from readthedocs.config.utils import list_to_dict, to_dict
+from readthedocs.projects.constants import GENERIC
 
 from .find import find_one
 from .models import (
@@ -1344,6 +1345,9 @@ def mkdocs(self):
 
     @property
     def doctype(self):
+        if getattr(self.build, "commands"):
+            return GENERIC
+
         if self.mkdocs:
             return 'mkdocs'
         return self.sphinx.builder

@@ -12,6 +12,7 @@
 from readthedocs.doc_builder.exceptions import BuildUserError
 from readthedocs.doc_builder.loader import get_builder_class
 from readthedocs.doc_builder.python_environments import Conda, Virtualenv
+from readthedocs.projects.constants import BUILD_COMMANDS_OUTPUT_PATH_HTML, GENERIC
 from readthedocs.projects.exceptions import RepositoryError
 from readthedocs.projects.models import Feature
 from readthedocs.projects.signals import after_build, before_build, before_vcs
@@ -348,9 +349,9 @@ def run_build_commands(self):
         # Copy files to artifacts path so they are uploaded to S3
         target = self.data.project.artifact_path(
             version=self.data.version.slug,
-            type_="sphinx",
+            type_=GENERIC,
         )
-        artifacts_path = os.path.join(cwd, "output")
+        artifacts_path = os.path.join(cwd, BUILD_COMMANDS_OUTPUT_PATH_HTML)
         if not os.path.exists(artifacts_path):
             raise BuildUserError(BuildUserError.BUILD_COMMANDS_WITHOUT_OUTPUT)
 

diff --git a/readthedocs/doc_builder/environments.py b/readthedocs/doc_builder/environments.py
@@ -315,8 +315,6 @@ def run(self):
                 cmd_stdout, cmd_stderr = out
             else:
                 cmd_stdout = out
-            # Docker returns None when there's no stderr/stdout
-            # so we need to convert that to a string.
             self.output = self.sanitize_output(cmd_stdout)
             self.error = self.sanitize_output(cmd_stderr)
             cmd_ret = client.exec_inspect(exec_id=exec_cmd['Id'])

@@ -3,6 +3,7 @@
 from django.utils.translation import gettext_noop
 
 from readthedocs.builds.constants import BUILD_STATE_CANCELLED, BUILD_STATUS_DUPLICATED
+from readthedocs.projects.constants import BUILD_COMMANDS_OUTPUT_PATH_HTML
 
 
 class BuildBaseException(Exception):
@@ -37,7 +38,7 @@ class BuildUserError(BuildBaseException):
         "dependencies are correct and have not changed recently."
     )
     BUILD_COMMANDS_WITHOUT_OUTPUT = gettext_noop(
-        'No "output/" folder detected on the root of the repository after building the project.'
+        f'No "{BUILD_COMMANDS_OUTPUT_PATH_HTML}" folder was created after building the project.'
     )
 
 

@@ -5,6 +5,7 @@
 theme names and repository types.
 """
 
+import os
 import re
 
 from django.utils.translation import gettext_lazy as _
@@ -14,14 +15,18 @@
 SPHINX_HTMLDIR = 'sphinx_htmldir'
 SPHINX_SINGLEHTML = 'sphinx_singlehtml'
 # This type is defined by the users in their mkdocs.yml file.
-MKDOCS_HTML = 'mkdocs_html'
+MKDOCS_HTML = "mkdocs_html"
+GENERIC = "generic"
 DOCUMENTATION_CHOICES = (
     (SPHINX, _('Sphinx Html')),
     (MKDOCS, _('Mkdocs')),
     (SPHINX_HTMLDIR, _('Sphinx HtmlDir')),
     (SPHINX_SINGLEHTML, _('Sphinx Single Page HTML')),
 )
-DOCTYPE_CHOICES = DOCUMENTATION_CHOICES + ((MKDOCS_HTML, _('Mkdocs Html Pages')),)
+DOCTYPE_CHOICES = DOCUMENTATION_CHOICES + (
+    (MKDOCS_HTML, _("Mkdocs Html Pages")),
+    (GENERIC, _("Generic")),
+)
 
 
 MEDIA_TYPE_HTML = 'html'
@@ -37,6 +42,9 @@
     MEDIA_TYPE_JSON,
 )
 
+BUILD_COMMANDS_OUTPUT_PATH = "_readthedocs/"
+BUILD_COMMANDS_OUTPUT_PATH_HTML = os.path.join(BUILD_COMMANDS_OUTPUT_PATH, "html")
+
 SAMPLE_FILES = (
     ('Installation', 'projects/samples/installation.rst.html'),
     ('Getting started', 'projects/samples/getting_started.rst.html'),

@@ -179,7 +179,7 @@
     <div class="build-ideas">
       <p>
         {% blocktrans trimmed with config_file_link="https://docs.readthedocs.io/page/build-customization.html#override-the-build-process-completely" %}
-        <strong><code>"build.commands"</code> config is in beta, use it under your own risks.</strong>
+        <strong>The <code>"build.commands"</code> feature is in beta, and could have backwards incompatible changes while in beta.</strong>
         Read more at <a href="{{ config_file_link }}">our documentation</a> to find out its limitations and potential issues.
         {% endblocktrans %}
       </p>