From ad36d86d2ccafd5a29cbcd9734fcdb31cc8d6595 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 15 Nov 2021 23:31:27 +0100 Subject: [PATCH 1/9] Add descriptive section to deployment section of tutorial --- doc/tutorial/deploying.rst | 57 ++++++++++++++++++++++++++++++++++++++ doc/tutorial/index.rst | 1 + 2 files changed, 58 insertions(+) create mode 100644 doc/tutorial/deploying.rst diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst new file mode 100644 index 00000000000..5d7227f7bf1 --- /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 6a5e7de5f07..1d12aff838a 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 From f16f4a249ba863f47d9b5e833fa7166897ce8c7a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Wed, 17 Nov 2021 21:37:01 +0100 Subject: [PATCH 2/9] Finish background section on deployment --- doc/tutorial/deploying.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst index 5d7227f7bf1..69476d7d978 100644 --- a/doc/tutorial/deploying.rst +++ b/doc/tutorial/deploying.rst @@ -55,3 +55,27 @@ All these options have zero cost, with the option of paying for extra features. .. _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/ From 7045505eaf1e1ecb985cc1d965280a06c01430cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 18 Nov 2021 10:19:14 +0100 Subject: [PATCH 3/9] Change focus to be broader and more descriptive --- doc/tutorial/deploying.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst index 69476d7d978..314bd3e2423 100644 --- a/doc/tutorial/deploying.rst +++ b/doc/tutorial/deploying.rst @@ -1,5 +1,5 @@ -Deploying a Sphinx project online -================================= +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, @@ -73,9 +73,6 @@ 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/ From 142c5cf853b82d3d00836e0786f4ed3b976f95d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 18 Nov 2021 10:19:38 +0100 Subject: [PATCH 4/9] Write how to publish documentation sources --- doc/tutorial/deploying.rst | 76 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst index 314bd3e2423..dd3a669896b 100644 --- a/doc/tutorial/deploying.rst +++ b/doc/tutorial/deploying.rst @@ -11,6 +11,10 @@ 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 ---------------------------------- @@ -76,3 +80,75 @@ 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 `_. +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 :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 `_. +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 :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 `_ is + not yet implemented. From 1d1b2296c5bd2faae9d291d838cbde38f8517148 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 18 Nov 2021 15:58:53 +0100 Subject: [PATCH 5/9] Describe deployment on Read the Docs and GitHub Pages --- doc/conf.py | 1 + doc/tutorial/deploying.rst | 73 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index 220774b7f6b..893761cde19 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -109,6 +109,7 @@ intersphinx_mapping = { 'python': ('https://docs.python.org/3/', None), 'requests': ('https://requests.readthedocs.io/en/master', None), + 'readthedocs': ('https://docs.readthedocs.io/en/stable', None), } # Sphinx document translation with sphinx gettext feature uses these settings: diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst index dd3a669896b..f4991379f07 100644 --- a/doc/tutorial/deploying.rst +++ b/doc/tutorial/deploying.rst @@ -152,3 +152,76 @@ learn more, you can: 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 :doc:`the RTD +tutorial `, which is loosely based on this one. +You can publish your sources on GitHub as explained :ref:`in the previous +section `, 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 ` 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 build + + on: push + + jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Build HTML + uses: ammaraskar/sphinx-action@0.4 + - name: Upload artifacts + uses: actions/upload-artifact@v1 + 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 + +.. todo:: + Some more changes are needed to tell the Sphinx action to install the + dependencies. + +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. + +After that, 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 From 043b5e925357d6eb6e5aa3a7cbfccc0f5be0743c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 18 Nov 2021 18:47:39 +0100 Subject: [PATCH 6/9] Add missing content on dependencies --- doc/tutorial/deploying.rst | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst index f4991379f07..08fa57ebc4f 100644 --- a/doc/tutorial/deploying.rst +++ b/doc/tutorial/deploying.rst @@ -205,10 +205,6 @@ contents: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: docs/build/html -.. todo:: - Some more changes are needed to tell the Sphinx action to install the - dependencies. - This contains a GitHub Actions workflow with a single job of four steps: 1. Checkout the code. @@ -218,9 +214,18 @@ This contains a GitHub Actions workflow with a single job of four steps: 4. If the change happens on the default branch, take the contents of ``docs/build/html`` and push it to the ``gh-pages`` branch. -After that, 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 +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. From daceb8aba3b0d90beb5ad6c84d8187284c5932df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 18 Nov 2021 19:34:09 +0100 Subject: [PATCH 7/9] Document GitLab Pages --- doc/tutorial/deploying.rst | 47 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst index 08fa57ebc4f..85fc6643ab5 100644 --- a/doc/tutorial/deploying.rst +++ b/doc/tutorial/deploying.rst @@ -230,3 +230,50 @@ select the ``gh-pages`` branch in the "Source" dropdown menu, and click 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 ` 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. From d39c6861d9542064cfa0a10878b1ce7317994602 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Tue, 23 Nov 2021 10:17:09 +0100 Subject: [PATCH 8/9] Add note about `.nojekyll` file --- doc/tutorial/deploying.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst index 85fc6643ab5..9f956a1f216 100644 --- a/doc/tutorial/deploying.rst +++ b/doc/tutorial/deploying.rst @@ -214,6 +214,15 @@ This contains a GitHub Actions workflow with a single job of four steps: 4. If the change happens on the default branch, take the contents of ``docs/build/html`` and push it to the ``gh-pages`` branch. +.. note:: + + The ``actions-gh-pages`` takes care of adding a ``.nojekyll`` file to the + output `so that GitHub Pages doesn't process it with its default + static site generator`__. Alternatively, you can enable the + :py:mod:`sphinx.ext.githubpages` extension on your project. + +.. __: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#static-site-generators + 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: From f6a3d037f4bf533dfae48998be98a86bd8cb93a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Sun, 28 Nov 2021 19:58:30 +0100 Subject: [PATCH 9/9] Remove note to simplify message --- doc/tutorial/deploying.rst | 9 --------- 1 file changed, 9 deletions(-) diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst index 9f956a1f216..85fc6643ab5 100644 --- a/doc/tutorial/deploying.rst +++ b/doc/tutorial/deploying.rst @@ -214,15 +214,6 @@ This contains a GitHub Actions workflow with a single job of four steps: 4. If the change happens on the default branch, take the contents of ``docs/build/html`` and push it to the ``gh-pages`` branch. -.. note:: - - The ``actions-gh-pages`` takes care of adding a ``.nojekyll`` file to the - output `so that GitHub Pages doesn't process it with its default - static site generator`__. Alternatively, you can enable the - :py:mod:`sphinx.ext.githubpages` extension on your project. - -.. __: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#static-site-generators - 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: