Add descriptive section to deployment section of tutorial

2 files changed, 58 insertions, 0 deletions

diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst
new file mode 100644
index 000000000..5d7227f7b
--- /dev/null
+++ b/doc/tutorial/deploying.rst
@@ -0,0 +1,57 @@
+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/
diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst
index 6a5e7de5f..1d12aff83 100644
--- a/doc/tutorial/index.rst
+++ b/doc/tutorial/index.rst
@@ -35,4 +35,5 @@ project.
    narrative-documentation
    describing-code
    automatic-doc-generation
+   deploying
    end