Merge pull request #8428 from readthedocs/rtd-tutorial-part-i

New Read the Docs tutorial, part I

docs/.rstcheck.cfg

@@ -1,7 +1,7 @@
 [rstcheck]
 ignore_directives=automodule,http:get,tabs,tab,prompt,http:patch,http:post,http:put,http:delete
 ignore_roles=djangosetting,setting,featureflags,buildpyversions
-ignore_substitutions=org_brand,com_brand,:smile:
+ignore_substitutions=org_brand,com_brand,:smile:,:arrows_counterclockwise:,:heavy_plus_sign:,:tada:,:heart:,:pencil2:
 # This error needs to be ignored for now
 # See: https://github.com/myint/rstcheck/issues/19
 ignore_messages=(Hyperlink target ".*" is not referenced)

docs/glossary.rst

@@ -0,0 +1,18 @@
+Glossary
+========
+
+.. glossary::
+
+   dashboard
+      `Main page <https://readthedocs.org/dashboard>`_ where you can see all your projects with their build status
+      and import a new project.
+
+   profile page
+      Page where you can see the projects of a certain user.
+
+   project home
+      Page where you can access all the features of Read the Docs,
+      from having an overview to browsing the latest builds or administering your project.
+
+   project page
+      Another name for :term:`project home`.

docs/index.rst

@@ -41,11 +41,13 @@ or are you looking to use your existing docs with Read the Docs?
 Learn about documentation authoring tools such as Sphinx and MkDocs
 to help you create fantastic documentation for your project.
 
+* **Tutorial**: :doc:`/tutorial/index`
+
 * **Getting started**:
   :doc:`With Sphinx </intro/getting-started-with-sphinx>` |
   :doc:`With MkDocs </intro/getting-started-with-mkdocs>` |
   :doc:`Feature Overview </features>` |
-  :doc:`/choosing-a-site`
+  :doc:`/choosing-a-site` | :doc:`/glossary`
 
 * **Importing your existing documentation**:
   :doc:`Import guide </intro/import-guide>`
@@ -56,12 +58,14 @@ to help you create fantastic documentation for your project.
    :hidden:
    :caption: First steps
 
+   /tutorial/index
    /intro/getting-started-with-sphinx
    /intro/getting-started-with-mkdocs
 
    /intro/import-guide
    /features
    /choosing-a-site
+   /glossary
 
 
 Getting started with Read the Docs

docs/intro/getting-started-with-sphinx.rst

@@ -4,7 +4,6 @@ Getting Started with Sphinx
 .. meta::
    :description lang=en: Get started writing technical documentation with Sphinx and publishing to Read the Docs.
 
-
 Sphinx is a powerful documentation generator that
 has many great features for writing technical documentation including:
 
@@ -16,6 +15,10 @@ has many great features for writing technical documentation including:
 * Syntax highlighted code samples
 * A vibrant ecosystem of first and third-party :doc:`extensions <sphinx:usage/extensions/index>`
 
+If you want to learn more about how to create your first Sphinx project, read on.
+If you are interested in exploring the Read the Docs platform using an already existing Sphinx project,
+check out :doc:`/tutorial/index`.
+
 Quick start
 -----------
 

docs/tutorial/index.rst

@@ -0,0 +1,288 @@
+Read the Docs tutorial
+======================
+
+In this tutorial you will create a documentation project on Read the Docs
+by importing an Sphinx project from a GitHub repository,
+tailor its configuration, and explore several useful features of the platform.
+
+The tutorial is aimed at people interested in learning
+how to use Read the Docs to host their documentation projects.
+You will fork a fictional software library
+similar to the one developed in the :doc:`official Sphinx tutorial <sphinx:tutorial/index>`.
+No prior experience with Sphinx is required,
+and you can follow this tutorial without having done the Sphinx one.
+
+The only things you will need to follow the are
+a web browser, an Internet connection, and a GitHub account
+(you can `register for a free account <https://github.com/signup>`_ if you don't have one).
+You will use Read the Docs Community, which means that the project will be public.
+
+Getting started
+---------------
+
+Preparing your project on GitHub
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To start, `sign in to GitHub <https://github.com/login>`_
+and navigate to `the tutorial GitHub template <https://github.com/astrojuanlu/tutorial-template/>`_,
+where you will see a green :guilabel:`Use this template` button.
+Click it to open a new page that will ask you for some details:
+
+* Leave the default "Owner", or change it to something better for a tutorial project.
+* Introduce an appropriate "Repository name", for example ``rtd-tutorial``.
+* Make sure the project is "Public", rather than "Private".
+
+After that, click on the green :guilabel:`Create repository from template` button,
+which will generate a new repository on your personal account
+(or the one of your choosing).
+This is the repository you will import on Read the Docs,
+and it contains the following files:
+
+``README.rst``
+  Basic description of the repository, you will leave it untouched.
+
+``pyproject.toml``
+  Python project metadata that makes it installable.
+  Useful for automatic documentation generation from sources.
+
+``lumache.py``
+  Source code of the fictional Python library.
+
+``docs/``
+  Directory holding all the Sphinx documentation sources,
+  including some required dependencies in ``docs/requirements.txt``,
+  the Sphinx configuration ``docs/source/conf.py``,
+  and the root document ``docs/source/index.rst`` written in reStructuredText.
+
+.. figure:: /_static/images/tutorial/github-template.png
+   :width: 80%
+   :align: center
+   :alt: GitHub template for the tutorial
+
+   GitHub template for the tutorial
+
+Sign up for Read the Docs
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To sign up for a Read the Docs account,
+navigate to the `Sign Up page <https://readthedocs.org/accounts/signup/>`_
+and choose the option :guilabel:`Sign up with GitHub`.
+On the authorization page, click the green :guilabel:`Authorize readthedocs` button.
+
+.. figure:: /_static/images/tutorial/github-authorization.png
+   :width: 60%
+   :align: center
+   :alt: GitHub authorization page
+
+   GitHub authorization page
+
+.. note::
+
+   Read the Docs needs elevated permissions to perform certain operations
+   that ensure that the workflow is as smooth as possible,
+   like installing webhooks.
+   If you want to learn more,
+   check out :ref:`connected-accounts:permissions for connected accounts`.
+
+After that, you will be redirected to Read the Docs,
+where you will need to confirm your e-mail and username.
+Clicking the :guilabel:`Sign Up »` button will create your account
+and redirect you to your :term:`dashboard`.
+
+By now, you should have two email notifications:
+
+* One from GitHub, telling you that "A third-party OAuth application ...
+  was recently authorized to access your account". You don't need to do
+  anything about it.
+* Another one from Read the Docs, prompting you to "verify your email
+  address". Click on the link to finalize the process.
+
+Finally, you created your account on Read the Docs
+and are ready to import your first project.
+
+Welcome!
+
+.. figure:: /_static/images/tutorial/rtd-empty-dashboard.png
+   :width: 80%
+   :align: center
+   :alt: Read the Docs empty dashboard
+
+   Read the Docs empty dashboard
+
+.. note::
+
+   Our commercial site offers some extra features,
+   like support for private projects.
+   You can learn more about :doc:`our two different sites </choosing-a-site>`.
+
+First steps
+-----------
+
+Importing the project to Read the Docs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To import your GitHub project to Read the Docs,
+first click on the :guilabel:`Import a Project` button on your dashboard
+(or browse to `the import page <https://readthedocs.org/dashboard/import/>`_ directly).
+You should see your GitHub account under the "Filter repositories" list on the right.
+If the list of repositories is empty, click the |:arrows_counterclockwise:| button,
+and after that all your repositories will appear on the center.
+
+.. figure:: /_static/images/tutorial/rtd-import-projects.gif
+   :width: 80%
+   :align: center
+   :alt: Import projects workflow
+
+   Import projects workflow
+
+Locate your ``rtd-tutorial`` project
+(possibly clicking :guilabel:`next ››` at the bottom if you have several pages of projects),
+and then click on the |:heavy_plus_sign:| button to the right of the name.
+The next page will ask you to fill some details about your Read the Docs project:
+
+Name
+  The name of the project. It has to be unique across all the service,
+  so it is better if you prepend your username,
+  for example ``astrojuanlu-rtd-tutorial``.
+
+Repository URL
+  The URL that contains the sources. Leave the automatically filled value.
+
+Repository type
+  Version control system used, leave it as "Git".
+
+Default branch
+  Name of the default branch of the project, leave it as ``main``.
+
+Edit advanced project options
+  Leave it unchecked, we will make some changes later.
+
+After hitting the :guilabel:`Next` button, you will be redirected to the :term:`project home`.
+You just created your first project on Read the Docs! |:tada:|
+
+.. figure:: /_static/images/tutorial/rtd-project-home.png
+   :width: 80%
+   :align: center
+   :alt: Project home
+
+   Project home
+
+Checking the first build
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Read the Docs will try to build the documentation of your project
+right after you create it.
+To see the build logs,
+click on the "Your documentation is building" link on the :term:`project home`,
+or alternatively navigate to the "Builds" page,
+then open the one on top (the most recent one).
+
+If the build has not finished yet by the time you open it,
+you will see a spinner next to a "Installing" or "Building" indicator,
+meaning that it is still in progress.
+
+.. figure:: /_static/images/tutorial/rtd-first-successful-build.png
+   :width: 80%
+   :align: center
+   :alt: First successful documentation build
+
+   First successful documentation build
+
+When the build finishes, you will see a green "Build completed" indicator,
+the completion date, the elapsed time,
+and a link to see the corresponding documentation.
+If you now click on "View docs", you will see your documentation live!
+
+.. figure:: /_static/images/tutorial/rtd-first-light.png
+   :width: 80%
+   :align: center
+   :alt: HTML documentation live on Read the Docs
+
+   HTML documentation live on Read the Docs
+
+.. note::
+
+   Advertisement is one of our main sources of revenue.
+   If you want to learn more about how do we fund our operations
+   and explore options to go ad-free,
+   check out our `Sustainability page <https://readthedocs.org/sustainability/>`_.
+
+   If you don't see the ad, you might be using an ad blocker.
+   Our Ethical Ads network respects your privacy, doesn't target you,
+   and tries to be as unobstrusive as possible,
+   so we would like to kindly ask you to :doc:`not block us </advertising/ad-blocking>` |:heart:|
+
+Basic configuration changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can now proceed to make some basic configuration adjustments.
+Navigate back to the :term:`project page`
+and click on the "⚙ Admin" button, which will open the Settings page.
+
+First of all, add the following text in the description:
+
+    Lumache (/lu'make/) is a Python library for cooks and food lovers
+    that creates recipes mixing random ingredients.
+
+Then set the project homepage to ``https://world.openfoodfacts.org/``,
+and write ``food, python`` in the list of tags.
+All this information will be shown on your project home.
+
+After that, configure your email so you get a notification if the build fails.
+To do so, click on the "Notifications" link on the left,
+type the email where you would like to get the notification,
+and click the "Add" button.
+After that, your email will be shown under "Existing Notifications".
+
+Trigger a build from a pull request
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Read the Docs allows you to :doc:`trigger builds from GitHub pull requests </pull-requests>`
+and gives you a preview of how the documentation would look like with those changes.
+
+To enable that functionality, first click on the "Advanced Settings" link on the left
+under the "⚙ Admin" menu, check the "Build pull requests for this project" checkbox,
+and click the :guilabel:`Save` button at the bottom of the page.
+
+Next, navigate to your GitHub repository, locate the file ``docs/source/index.rst``,
+and click on the |:pencil2:| icon on the top-right with the tooltip "Edit this file"
+to open a web editor (more information `on their documentation`__).
+
+__  https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/editing-files-in-your-repository
+
+.. figure:: /_static/images/tutorial/gh-edit.png
+   :width: 80%
+   :align: center
+   :alt: File view on GitHub before launching the editor
+
+   File view on GitHub before launching the editor
+
+In the editor, add the following sentence to the file:
+
+    Lumache has its documentation hosted on Read the Docs.
+
+Write an appropriate commit message,
+and choose the "Create a **new branch** for this commit and start a pull request" option,
+typing a name for the new branch.
+When you are done, click the green :guilabel:`Propose changes` button,
+which will take you to the new pull request page,
+and there click the :guilabel:`Create pull request` button below the description.
+
+.. figure:: /_static/images/tutorial/gh-pr-build.png
+   :width: 80%
+   :align: center
+   :alt: Read the Docs building the pull request from GitHub
+
+   Read the Docs building the pull request from GitHub
+
+After opening the pull request, a Read the Docs check will appear
+indicating that it is building the documentation for that pull request.
+If you click on the "Details" link while it is building,
+you will access the build logs,
+otherwise it will take you directly to the documentation.
+When you are satisfied, you can merge the pull request!
+
+----
+
+That's the end of the tutorial,
+but you can learn more about the platform starting with our :doc:`/features` page.