https://blog.readthedocs.comRead the Docs Blog - Posts tagged feature2024-01-10T23:05:10.909948+00:00ABloghttps://blog.readthedocs.com/build-customization/Override the build process completely with build.commands2022-11-14T00:00:00+00:00Manuel Kaufmann<section id="override-the-build-process-completely-with-build-commands">
<p>We are happy to announce a new <em>beta</em> feature that allows users to <strong>override the Read the Docs build process completely</strong>.
We previously talked about <a class="reference external" href="https://blog.readthedocs.com/user-defined-build-jobs/">executing custom commands</a> <em>in-between</em> the Read the Docs build process.
That approach is not sufficient for projects with a heavily customized build process,
or those that want to use a different documentation tool like <a class="reference external" href="https://getpelican.com/">Pelican</a>, <a class="reference external" href="https://docsify.js.org/">Docsify</a> and <a class="reference external" href="https://docusaurus.io/">Docusaurus</a> for their documentation.
Some of which were not able to use our platform at all.
Until now! We have good news for them!</p>
<p>The new configuration file option <code class="docutils literal notranslate"><span class="pre">build.commands</span></code> allows projects to only execute <em>exactly</em> the commands they want.
No more. No less.
This means that Read the Docs <em>won’t execute any of the default commands</em> behind the scenes.
You have 100% control over the build process.</p>
<section id="how-does-it-work">
<h2>How does it work?</h2>
<p>To use the new <em>beta</em> feature,
you can specify all the commands the build process requires under the <code class="docutils literal notranslate"><span class="pre">build.commands</span></code> <a class="reference external" href="https://docs.readthedocs.io/en/stable/config-file/v2.html#build-commands">config key</a>.
Finally, move the resulting documentation artifacts into the <code class="docutils literal notranslate"><span class="pre">_readthedocs/html</span></code> directory.
Read the Docs will upload and host all the content of that folder ✨</p>
<p>Here is simple example that builds the Docusaurus tutorial:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">version</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2</span>
<span class="nt">build</span><span class="p">:</span>
<span class="w"> </span><span class="nt">os</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ubuntu-22.04</span>
<span class="w"> </span><span class="nt">tools</span><span class="p">:</span>
<span class="w"> </span><span class="nt">nodejs</span><span class="p">:</span><span class="w"> </span><span class="s">"18"</span>
<span class="w"> </span><span class="nt">commands</span><span class="p">:</span>
<span class="w"> </span><span class="c1"># "docs/" directory was created using the command to create the site:</span>
<span class="w"> </span><span class="c1"># npx create-docusaurus@latest docs classic</span>
<span class="w"> </span><span class="c1">#</span>
<span class="w"> </span><span class="c1"># Install Docusaurus dependencies</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">cd docs/ && npm install</span>
<span class="w"> </span><span class="c1"># Build the site</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">cd docs/ && npm run build</span>
<span class="w"> </span><span class="c1"># Copy generated files into Read the Docs directory</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">mkdir --parents _readthedocs/html/</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">cp --recursive docs/build/* _readthedocs/html/</span>
</pre></div>
</div>
<p>The resulting documentation lives at <a class="reference external" href="https://test-builds.readthedocs.io/en/docusaurus/">https://test-builds.readthedocs.io/en/docusaurus/</a>.</p>
<p>If you want to read more about <code class="docutils literal notranslate"><span class="pre">build.commands</span></code>,
<a class="reference external" href="https://docs.readthedocs.io/en/latest/build-customization.html">read the full documentation</a>.</p>
</section>
<section id="limitations">
<h2>Limitations</h2>
<p>This feature is still in <em>beta</em> and has some limitation currently.
We are working to make <code class="docutils literal notranslate"><span class="pre">build.commands</span></code> more integrated into our platform.
One major missing feature is the flyout, which gives access to downloads, versions and other functionality.
We are actively working on improving this feature,
and we will publishing more content about this in the next months.
Stay tuned!</p>
</section>
<section id="try-it-out-and-give-us-feedback">
<h2>Try it out and give us feedback!</h2>
<p>We want to continue improving this <em>beta</em> feature.
It has lot of potential and we want to develop it in a way that’s useful for our users.
Please, give it a try and <a class="reference external" href="mailto:support%40readthedocs.com">let us know</a> how are you using it and if it’s missing something for your use case.</p>
</section>
</section>
We are happy to announce a new beta feature that allows users to override the Read the Docs build process completely.
We previously talked about executing custom commands in-between the Read the Docs build process.
That approach is not sufficient for projects with a heavily customized build process,
or those that want to use a different documentation tool like Pelican, Docsify and Docusaurus for their documentation.
Some of which were not able to use our platform at all.
Until now! We have good news for them!The new configuration file option build.commands allows projects to only execute exactly the commands they want.
No more. No less.
This means that Read the Docs won’t execute any of the default commands behind the scenes.
You have 100% control over the build process.2022-11-14T00:00:00+00:00