Appendix: 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.

The following sections describe some of the available options to
deploy your online documentation, and give some background
information. If you want to go directly to the practical part, you can
skip to Publishing your documentation sources.


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.


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.


Publishing your documentation sources
=====================================


GitHub
------

The quickest way to upload an existing project to GitHub is to:

1. Sign up for a GitHub account.

2. Create a new repository.

3. Open the "Upload files" page of your new repository.

4. Select the files on your operating system file browser (in your
   case "README.rst", "lumache.py", the makefiles under the "docs"
   directory, and everything under "docs/source") and drag them to the
   GitHub interface to upload them all.

5. Click on the Commit changes button.

Note:

  Make sure you don't upload the "docs/build" directory, as it
  contains the output generated by Sphinx and it will change every
  time you change the sources, complicating your workflow.

These steps do not require access to the command line or installing
any additional software. To learn more, you can:

* Follow this interactive GitHub course to learn more about how the
  GitHub interface works.

* Read this quickstart tutorial to install extra software on your
  machine and have more flexibility. You can either use the Git
  command line, or the GitHub Desktop application.


GitLab
------

Similarly to GitHub, the fastest way to upload your project to GitLab
is using the web interface:

1. Sign up for a GitLab account.

2. Create a new blank project.

3. Upload the project files (in your case "README.rst", "lumache.py",
   the makefiles under the "docs" directory, and everything under
   "docs/source") one by one using the Upload File button [1].

Again, these steps do not require additional software on your
computer. To learn more, you can:

* Follow this tutorial to install Git on your machine.

* Browse the GitLab User documentation to understand the possibilities
  of the platform.

Note:

  Make sure you don't upload the "docs/build" directory, as it
  contains the output generated by Sphinx and it will change every
  time you change the sources, complicating your workflow.

[1] At the time of writing, uploading whole directories to GitLab
    using only the web interface is not yet implemented.


Publishing your HTML documentation
==================================


Read the Docs
-------------

Read the Docs offers integration with both GitHub and GitLab. The
quickest way of getting started is to follow *the RTD tutorial*, which
is loosely based on this one. You can publish your sources on GitHub
as explained in the previous section, then skip directly to Sign up
for Read the Docs. If you choose GitLab instead, the process is
similar.


GitHub Pages
------------

GitHub Pages requires you to publish your sources on GitHub. After
that, you will need an automated process that performs the "make html"
step every time the sources change. That can be achieved using GitHub
Actions.

After you have published your sources on GitHub, create a file named
".github/workflows/sphinx.yml" in your repository with the following
contents:

.github/workflows/

   name: Sphinx build

   on: push

   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
       - uses: actions/checkout@v3
       - name: Build HTML
         uses: ammaraskar/sphinx-action@master
       - name: Upload artifacts
         uses: actions/upload-artifact@v3
         with:
           name: html-docs
           path: docs/build/html/
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
         if: github.ref == 'refs/heads/main'
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: docs/build/html

This contains a GitHub Actions workflow with a single job of four
steps:

1. Checkout the code.

2. Build the HTML documentation using Sphinx.

3. Attach the HTML output the artifacts to the GitHub Actions job, for
   easier inspection.

4. If the change happens on the default branch, take the contents of
   "docs/build/html" and push it to the "gh-pages" branch.

Next, you need to specify the dependencies for the "make html" step to
be successful. For that, create a file "docs/requirements.txt" and add
the following contents:

docs/requirements.txt

   furo==2021.11.16

And finally, you are ready to enable GitHub Pages on your repository.
For that, go to Settings, then Pages on the left sidebar, select the
"gh-pages" branch in the "Source" dropdown menu, and click Save. After
a few minutes, you should be able to see your HTML at the designated
URL.


GitLab Pages
------------

GitLab Pages, on the other hand, requires you to publish your sources
on GitLab. When you are ready, you can automate the process of running
"make html" using GitLab CI.

After you have published your sources on GitLab, create a file named
".gitlab-ci.yml" in your repository with these contents:

.gitlab-ci.yml

   stages:
     - deploy

   pages:
     stage: deploy
     image: python:3.9-slim
     before_script:
       - apt-get update && apt-get install make --no-install-recommends -y
       - python -m pip install sphinx furo
     script:
       - cd docs && make html
     after_script:
       - mv docs/build/html/ ./public/
     artifacts:
       paths:
       - public
     rules:
       - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

This contains a GitLab CI workflow with one job of several steps:

1. Install the necessary dependencies.

2. Build the HTML documentation using Sphinx.

3. Move the output to a known artifacts location.

Note:

  You will need to validate your account by entering a payment method
  (you will be charged a small amount that will then be reimbursed).

After that, if the pipeline is successful, you should be able to see
your HTML at the designated URL.
