diff options
Diffstat (limited to 'doc/tutorial/deploying.rst')
| -rw-r--r-- | doc/tutorial/deploying.rst | 281 |
1 files changed, 281 insertions, 0 deletions
diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst new file mode 100644 index 0000000..e16abdf --- /dev/null +++ b/doc/tutorial/deploying.rst @@ -0,0 +1,281 @@ +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 :ref:`publishing-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. + +.. _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. + +.. _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/ + +.. _publishing-sources: + +Publishing your documentation sources +------------------------------------- + +GitHub +~~~~~~ + +The quickest way to upload an existing project to GitHub is to: + +1. `Sign up for a GitHub account <https://github.com/signup>`_. +2. `Create a new repository <https://github.com/new>`_. +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 :guilabel:`Commit changes` button. + +.. _the "Upload files" page: https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository + +.. 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. + +.. _this interactive GitHub course: https://lab.github.com/githubtraining/introduction-to-github +.. _this quickstart tutorial: https://docs.github.com/en/get-started/quickstart + +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 <https://gitlab.com/users/sign_up>`_. +2. `Create a new blank project <https://gitlab.com/projects/new>`_. +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 :guilabel:`Upload File` button [#f1]_. + +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. + +.. _this tutorial: https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html +.. _GitLab User documentation: https://docs.gitlab.com/ee/user/index.html + +.. 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. + +.. [#f1] At the time of writing, `uploading whole directories to GitLab using + only the web + interface <https://gitlab.com/gitlab-org/gitlab/-/issues/228490>`_ 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 :doc:`the RTD +tutorial <readthedocs:tutorial/index>`, which is loosely based on this one. +You can publish your sources on GitHub as explained :ref:`in the previous +section <publishing-sources>`, then skip directly to +:ref:`readthedocs:tutorial/index:Sign up for Read the Docs`. +If you choose GitLab instead, the process is similar. + +GitHub Pages +~~~~~~~~~~~~ + +`GitHub Pages`_ requires you to :ref:`publish your +sources <publishing-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: + +.. code-block:: yaml + :caption: .github/workflows/ + + name: "Sphinx: Render docs" + + on: push + + jobs: + build: + runs-on: ubuntu-latest + permissions: + contents: write + 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: + +.. code-block:: + :caption: docs/requirements.txt + + furo==2021.11.16 + +And finally, you are ready to `enable GitHub Pages on your repository`_. For +that, go to :guilabel:`Settings`, then :guilabel:`Pages` on the left sidebar, +select the ``gh-pages`` branch in the "Source" dropdown menu, and click +:guilabel:`Save`. After a few minutes, you should be able to see your HTML at +the designated URL. + +.. _enable GitHub Pages on your repository: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site + +GitLab Pages +~~~~~~~~~~~~ + +`GitLab Pages`_, on the other hand, requires you to :ref:`publish your +sources <publishing-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: + +.. code-block:: yaml + :caption: .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). + +.. _validate your account: https://about.gitlab.com/blog/2021/05/17/prevent-crypto-mining-abuse/#validating-an-account + +After that, if the pipeline is successful, you should be able to see your HTML +at the designated URL. |