sphinx/doc/tutorial/deploying.rst

Deploying a Sphinx project online
=================================

When you are ready to show your documentation project to the world, there are
many options available to do so. Since the HTML generated by Sphinx is static,
you can decouple the process of building your HTML documentation from hosting
such files in the platform of your choice. You will not need a sophisticated
server running Python: virtually every web hosting service will suffice.

Therefore, the challenge is less how or where to serve the static HTML, but
rather how to pick a workflow that automatically updates the deployed
documentation every time there is a change in the source files.

Sphinx-friendly deployment options
----------------------------------

There are several possible options you have to host your Sphinx documentation.
Some of them are:

**Read the Docs**
   `Read the Docs`_ is an online service specialized in hosting technical
   documentation written in Sphinx, as well as MkDocs. They have a
   number of extra features, such as versioned documentation, traffic and
   search analytics, custom domains, user-defined redirects, and more.

**GitHub Pages**
   `GitHub Pages`_ is a simple static web hosting tightly integrated with
   `GitHub`_: static HTML is served from one of the branches of a project,
   and usually sources are stored in another branch so that the output
   can be updated every time the sources change (for example using `GitHub
   Actions`_). It is free to use and supports custom domains.

**GitLab Pages**
   `GitLab Pages`_ is a similar concept to GitHub Pages, integrated with
   `GitLab`_ and usually automated with `GitLab CI`_ instead.

**Netlify**
   `Netlify`_ is a sophisticated hosting for static sites enhanced by
   client-side web technologies like JavaScript (so-called `"Jamstack"`_).
   They offer support for headless content management systems and
   serverless computing.

**Your own server**
   You can always use your own web server to host Sphinx HTML documentation.
   It is the option that gives more flexibility, but also more complexity.

All these options have zero cost, with the option of paying for extra features.

.. _Read the Docs: https://readthedocs.org/
.. _GitHub Pages: https://pages.github.com/
.. _GitHub: https://github.com/
.. _GitHub Actions: https://github.com/features/actions
.. _GitLab Pages: https://about.gitlab.com/stages-devops-lifecycle/pages/
.. _GitLab: https://gitlab.com/
.. _GitLab CI: https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/
.. _Netlify: https://www.netlify.com/
.. _"Jamstack": https://jamstack.org/

Embracing the "Docs as Code" philosophy
---------------------------------------

The free offerings of most of the options listed above require your
documentation sources to be publicly available. Moreover, these services
expect you to use a `Version Control System`_, a technology that tracks the
evolution of a collection of files as a series of snapshots ("commits").
The practice of writing documentation in plain text files with the same tools
as the ones used for software development is commonly known as `"Docs as Code"`_.

The most popular Version Control System nowadays is Git_, a free and open
source tool that is the backbone of services like GitHub and GitLab.
Since both Read the Docs and Netlify have integrations with GitHub and GitLab,
and both GitHub and GitLab have an integrated Pages product, the most effective
way of automatically build your documentation online is to upload your sources
to either of these Git hosting services.

The rest of this section will focus on GitHub, which is the most popular Git
hosting service nowadays. It is very similar to GitLab.

.. _Version Control System: https://en.wikipedia.org/wiki/Version_control
.. _"Docs as Code": https://www.writethedocs.org/guide/docs-as-code/
.. _Git: https://git-scm.com/