https://blog.readthedocs.comRead the Docs Blog - Posts by Maksudul Haque2024-01-10T23:05:10.255889+00:00ABloghttps://blog.readthedocs.com/building-docs-for-pull-requests/GSOC 2019: Autobuild Documentation for Pull Requests2019-08-14T00:00:00+00:00Maksudul Haque<section id="gsoc-2019-autobuild-documentation-for-pull-requests">
<p>Building documentation for pull requests is one of the most requested features of Read the Docs.
Similar to how a continuous integration system runs a test suite on every pull request,
this change would build the documentation for each pull request
and send build status notification to the providers’ Status API (e.g. Github Status API).
This will let users check if the documentation build passed
and also how the documentation looks before merging it to master.</p>
<p>As a student of Google Summer of Code (GSoC) 2019, I (<a class="reference external" href="https://github.com/saadmk11">Maksudul Haque</a>) was tasked with building this feature.
The main goal of my project was to make it possible to build documentation whenever a pull request was created,
and send build status notification to the Providers’ Status API.</p>
<p>To see this feature in action you can click on one of the <a class="reference external" href="https://github.com/readthedocs/readthedocs.org/pulls">pull requests</a> on readthedocs.org repository.</p>
<figure class="align-default" id="id1">
<img alt="GitHub Build Status Reporting for Pull Requests." src="../../../_images/github-build-status-reporting.gif" style="width: 70%;" />
<figcaption>
<p><span class="caption-text">GitHub Build Status Reporting for Pull Requests</span></p>
</figcaption>
</figure>
</section>
<section id="google-summer-of-code">
<h1>Google Summer of Code</h1>
<p>Google Summer of Code is a global program where students work with an open source organization
on a 3 month programming project. <strong>Autobuild Documentation for Pull Requests</strong> was one of the project ideas on
Read the Docs <a class="reference external" href="https://github.com/readthedocs/readthedocs.org/blob/3.5.3/docs/gsoc.rst#autobuild-docs-for-pull-requests">Project Ideas</a> for Google Summer of Code 2019. I applied for the project and got accepted.</p>
<p>I started working on this project since May 2019.
All of my work on this project can be seen in the <a class="reference external" href="https://github.com/orgs/readthedocs/projects/8">Pull Request Builder Board</a>.</p>
</section>
<section id="background">
<h1>Background</h1>
<p>Many of our users wanted a way to visualize the documentation update that was made in a pull request.
They also want to know whether the documentation build will pass before merging the pull request to master.
This would allow users to have more confidence on the pull request
and make the pull request less likely to break the documentation after merging.
So, to achieve this Read the Docs <a class="reference external" href="https://docs.readthedocs.io/en/latest/team.html#development-team">core team</a> selected <strong>Autobuild Documentation for Pull Requests</strong>
as one of the projects of Google Summer of Code 2019.</p>
</section>
<section id="pull-request-builder-features">
<h1>Pull Request Builder Features</h1>
<p>Currently I have implemented these features and working on more upcoming features.
Some of the major features are as follows:</p>
<ul class="simple">
<li><p><strong>Creating External Versions:</strong> We create an external version when we receive a pull request
webhook event for a project from GitHub and trigger a build for that version.
External versions are short-lived versions that are separate from the project’s main documentation.</p></li>
<li><p><strong>Synchronizing External Versions:</strong> Whenever there is a new commit on the pull request,
we synchronize the external version for that pull request and trigger a new documentation build with the latest changes.</p></li>
<li><p><strong>Deleting External Versions:</strong> Whenever the pull request is closed or merged,
we delete the external Version associated with that pull request.</p></li>
<li><p><strong>Warning Banner for pull request documentation:</strong> While building documentation for pull requests
we add a warning banner at the top of those documentations to let the users know that
this documentation was generated for pull requests and is not the main documentation for the project.</p></li>
</ul>
<p>We send build status reports to the status API of the provider (e.g. GitHub).
When a build is triggered for a pull request we send build pending notification with the build URL
and after the build has finished we send success notification if the build succeeded without any error
or failure notification if the build failed.
By going to the build URL provided in the status report users can view the build steps
and also see the documentation generated by that build.</p>
<p><strong>Currently, we only support GitHub and planning to extend to GitLab and BitBucket.</strong></p>
</section>
<section id="getting-started">
<h1>Getting Started</h1>
<p>Building documentation for pull requests is currently in Beta testing and only supports Github repositories.
If you want to dive in and enable this feature for your project you can <a class="reference external" href="mailto:support%40readthedocs.org">email us</a>
with the URL of your ReadtheDocs project.</p>
</section>
<section id="future-improvements">
<h1>Future Improvements</h1>
<p>We are planing to extend this feature to other platforms such as GitLab and BitBucket.
We are also planning to make this feature more customizable through our configuration file (<code class="docutils literal notranslate"><span class="pre">.readthedocs.yaml</span></code>).
If you have any improvements or features in mind for building documentation for Pull requests we would love to know about it.
Please feel free to let us know by submitting an <a class="reference external" href="https://github.com/readthedocs/readthedocs.org/issues/new">issue on GitHub</a>.</p>
</section>
<section id="contributors-wanted">
<h1>Contributors Wanted</h1>
<p>As Read the Docs is an open source project backed by a small team of developers,
most of them are busy to keep things up and running only. Therefore, its quite
hard for them to take time to implement new features. We would like to get more contributors
to improve this feature. If you know a bit of Django and Python and interested to improve this feature
you are always welcome to contribute. If you need any support to start contributing, you can get in touch with
me or any other member of Read the Docs team. You can find all of us at <cite>#readthedocs</cite> freenode
IRC channel or <a class="reference external" href="https://gitter.im/rtfd/readthedocs.org">readthedocs gitter</a> channel. I am <cite>saadmk11</cite> at IRC and <cite>@saadmk11</cite> at gitter.</p>
</section>
<section id="conclusion">
<h1>Conclusion</h1>
<p>To conclude, I would like to say this was a much needed feature for Read the Docs and also its users.
This feature will improve our platform and make it a true Continuous Documentation platform.
I think that many users will benefit from this feature.
We will keep making improvements along the way for a better user experience.</p>
</section>
Building documentation for pull requests is one of the most requested features of Read the Docs.
Similar to how a continuous integration system runs a test suite on every pull request,
this change would build the documentation for each pull request
and send build status notification to the providers’ Status API (e.g. Github Status API).
This will let users check if the documentation build passed
and also how the documentation looks before merging it to master.As a student of Google Summer of Code (GSoC) 2019, I (Maksudul Haque) was tasked with building this feature.
The main goal of my project was to make it possible to build documentation whenever a pull request was created,
and send build status notification to the Providers’ Status API.2019-08-14T00:00:00+00:00