diff options
| -rw-r--r-- | doc/tutorial/deploying.rst | 76 |
1 files changed, 76 insertions, 0 deletions
diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst index 314bd3e24..dd3a66989 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 <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. |