When you are ready to show your documentation project to the world, there aremany options available to do so. Since the HTML generated by Sphinx is static,you can decouple the process of building your HTML documentation from hostingsuch files in the platform of your choice. You will not need a sophisticatedserver running Python: virtually every web hosting service will suffice.
Therefore, the challenge is less how or where to serve the static HTML, butrather how to pick a workflow that automatically updates the deployeddocumentation every time there is a change in the source files.
The following sections describe some of the available options to deployyour online documentation, and give some background information. If you wantto 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 technicaldocumentation written in Sphinx, as well as MkDocs. They have anumber of extra features, such as versioned documentation, traffic andsearch analytics, custom domains, user-defined redirects, and more.
- GitHub Pages
GitHub Pages is a simple static web hosting tightly integrated withGitHub: static HTML is served from one of the branches of a project,and usually sources are stored in another branch so that the outputcan be updated every time the sources change (for example using GitHubActions). It is free to use and supports custom domains.
- GitLab Pages
GitLab Pages is a similar concept to GitHub Pages, integrated withGitLab and usually automated with GitLab CI instead.
- Netlify
Netlify is a sophisticated hosting for static sites enhanced byclient-side web technologies like JavaScript (so-called “Jamstack”).They offer support for headless content management systems andserverless 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 yourdocumentation sources to be publicly available. Moreover, these servicesexpect you to use a Version Control System, a technology that tracks theevolution of a collection of files as a series of snapshots (“commits”).The practice of writing documentation in plain text files with the same toolsas 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 opensource 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 effectiveway of automatically build your documentation online is to upload your sourcesto either of these Git hosting services.
Publishing your documentation sources¶
GitHub¶
The quickest way to upload an existing project to GitHub is to:
Open the “Upload files” page of your new repository.
Select the files on your operating system file browser (in your case
README.rst,lumache.py, the makefiles under thedocsdirectory,and everything underdocs/source) and drag them to the GitHub interfaceto upload them all.Click on the Commit changes button.
Note
Make sure you don’t upload the docs/build directory, as it contains theoutput generated by Sphinx and it will change every time you change thesources, complicating your workflow.
These steps do not require access to the command line or installing anyadditional software. To learn more, you can:
Follow this interactive GitHub course to learn more about how the GitHubinterface works.
Read this quickstart tutorial to install extra software on your machineand have more flexibility. You can either use the Git command line, or theGitHub Desktop application.
GitLab¶
Similarly to GitHub, the fastest way to upload your project to GitLab isusing the web interface:
Upload the project files (in your case
README.rst,lumache.py, themakefiles under thedocsdirectory, and everything underdocs/source) one by one using the Upload File button [1].
Again, these steps do not require additional software on your computer. Tolearn more, you can:
Follow this tutorial to install Git on your machine.
Browse the GitLab User documentation to understand the possibilities ofthe platform.
Note
Make sure you don’t upload the docs/build directory, as it contains theoutput generated by Sphinx and it will change every time you change thesources, complicating your workflow.
Publishing your HTML documentation¶
Read the Docs¶
Read the Docs offers integration with both GitHub and GitLab. The quickestway of getting started is to follow the RTDtutorial, which is loosely based on this one.You can publish your sources on GitHub as explained in the previoussection, then skip directly toSign up for Read the Docs.If you choose GitLab instead, the process is similar.
GitHub Pages¶
GitHub Pages requires you to publish yoursources on GitHub. After that, you will need anautomated process that performs the make html step every time the sourceschange. 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 followingcontents:
.github/workflows/¶
name: "Sphinx: Render docs"on: pushjobs: build: runs-on: ubuntu-latest permissions: contents: write steps: - uses: actions/checkout@v4 - name: Build HTML uses: ammaraskar/sphinx-action@master - name: Upload artifacts uses: actions/upload-artifact@v4 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:
Checkout the code.
Build the HTML documentation using Sphinx.
Attach the HTML output the artifacts to the GitHub Actions job, for easierinspection.
If the change happens on the default branch, take the contents of
docs/build/htmland push it to thegh-pagesbranch.
Next, you need to specify the dependencies for the make html step to besuccessful. For that, create a file docs/requirements.txt and add thefollowing contents:
docs/requirements.txt¶
furo==2021.11.16
And finally, you are ready to enable GitHub Pages on your repository. Forthat, go to Settings, then Pages on the left sidebar,select the gh-pages branch in the “Source” dropdown menu, and clickSave. After a few minutes, you should be able to see your HTML atthe designated URL.
GitLab Pages¶
GitLab Pages, on the other hand, requires you to publish yoursources on GitLab. When you are ready, you canautomate 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: - deploypages: 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:
Install the necessary dependencies.
Build the HTML documentation using Sphinx.
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 HTMLat the designated URL.
