Build: implement build.jobs config file key

readthedocs/config/config.py

@@ -802,9 +802,6 @@ def validate_build_config_with_tools(self):
             )
 
         build["jobs"] = {}
-        for job in BuildJobs.__slots__:
-            build["jobs"][job] = []
-
         for job, commands in jobs.items():
             with self.catch_validation_error(f"build.jobs.{job}"):
                 build["jobs"][job] = [

readthedocs/config/models.py

@@ -64,6 +64,11 @@ class BuildJobs(Base):
         "post_build",
     )
 
+    def __init__(self, **kwargs):
+        for step in self.__slots__:
+            kwargs.setdefault(step, [])
+        super().__init__(**kwargs)
+
 
 class Python(Base):
 

readthedocs/doc_builder/director.py

@@ -291,6 +291,33 @@ def build_epub(self):
         return False
 
     def run_build_job(self, job):
+        """
+        Run a command specified by the user under `build.jobs.` config key.
+
+        It uses the "VCS environment" for pre_/post_ checkout jobs and "build
+        environment" for the rest of them.
+
+        Note that user's commands:
+
+        - are not escaped
+        - are run with under the path where the repository was cloned
+        - are run as RTD_DOCKER_USER user
+        - users can't run commands as `root` user
+        - all the user's commands receive environment variables
+
+        Example:
+
+          build:
+            jobs:
+              pre_install:
+                - echo `date`
+                - python path/to/myscript.py
+              pre_build:
+                - sed -i **/*.rst -e "s|{version}|v3.5.1|g"
+
+        In this case, `self.data.config.build.jobs.pre_build` will contains
+        `sed` command.
+        """
         if (
             getattr(self.data.config.build, "jobs", None) is None
             or getattr(self.data.config.build.jobs, job, None) is None