Skip to content

Tighten up and refactor the tutorial WIP #11316

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
May 23, 2024
Merged

Tighten up and refactor the tutorial WIP #11316

Changes from 8 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
8bd774b
Tighten up and refactor the tutorial
plaindocs May 8, 2024
25276fc
Second half of the doc edits
plaindocs May 22, 2024
b168970
Apply suggestions from code review
plaindocs May 22, 2024
7817418
Refactor conf options
plaindocs May 22, 2024
31fc63e
Less Python version maintenance
plaindocs May 22, 2024
db59035
Use ref for links
plaindocs May 22, 2024
a6d147f
Or just say next
plaindocs May 22, 2024
0db5f12
Use ref for link to hading
plaindocs May 22, 2024
f787fbb
Cleanup bullets
plaindocs May 22, 2024
a2195b4
Fix whitespace, thanks pre-commit
plaindocs May 23, 2024
b2f03ab
Update docs/user/tutorial/index.rst
plaindocs May 23, 2024
c815113
Condense email shenanigans
plaindocs May 23, 2024
064bb18
Apply suggestions from code review
plaindocs May 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
202 changes: 82 additions & 120 deletions docs/user/tutorial/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ On the authorization page, click the green :guilabel:`Authorize readthedocs` but
check out :ref:`guides/setup/git-repo-automatic:permissions for connected accounts`.

After that, you will be redirected to Read the Docs to confirm your e-mail and username. Click the :guilabel:`Sign Up »` button to create your account and
and open your :term:`dashboard`.
open your :term:`dashboard`.

You should have two email notifications:

Expand All @@ -89,7 +89,7 @@ You should have two email notifications:
* Another one from Read the Docs, prompting you to "verify your email
address". Click on the link to finalize the process.

After veryifyng your email address, your Read the Docs account is ready to import your first project.
After verifying your email address, your Read the Docs account will be ready to create your first project.

.. figure:: /_static/images/tutorial/rtd-empty-dashboard.png
:width: 80%
Expand Down Expand Up @@ -185,14 +185,14 @@ To update the project description and configure the notification settings:

#. Navigate back to the :term:`project page` and click the :guilabel:`⚙ Admin` button,to open the Settings page.

#. Update the poject description by adding the following text:
#. Update the project description by adding the following text:

Lumache (/lu'make/) is a Python library for cooks and food lovers
that creates recipes mixing random ingredients.

#. Set the project homepage to ``https://world.openfoodfacts.org/``, and add ``food, python`` to the list of public project tags.

#. To get a notification if the build fails, click the :guilabel:`Notifications` link on the left, add your email address, and click the :guilabel:`Add` button.
#. To get a notification if the build fails, click the :guilabel:`Email Notifications` link on the left, add your email address, and click the :guilabel:`Add` button.

Triggering builds from pull requests
------------------------------------
Expand Down Expand Up @@ -237,35 +237,25 @@ To trigger builds from pull requests:

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 the :guilabel:`Details` link while it is building,
it opens the build log, after than it opens the documentation directly.
If you click the :guilabel:`Details` link while your project is building
the build log will be opened. After building this link opens the documentation directly.

Adding a configuration file
---------------------------

The Admin tab of the :term:`project home` has some *global* configuration settings for your project.

In addition, you can customize the build process using the ``.readthedocs.yaml`` :doc:`configuration file </config-file/v2>`, which has several advantages:

- The configuration lives next to your code and documentation, tracked by version control.
- The configuration can be different for every version or branch of your project (more on `versioning <#versioning-documentation>`_).
- Some configuration optionss are only available using the configuration file.

This configuration file, ``.readthedocs.yaml``, is already in your Git repository, located in the base folder of the repository.
Build process configuration settings are in ``.readthedocs.yaml`` :doc:`configuration file </config-file/v2>`, in your Git repository, which means it can be different for every version or branch of your project (more on `versioning <#versioning-documentation>`_).

.. TODO: We are adding a how-to that we need to include in this tutorial.
.. Maybe by reference or maybe as full-featured content.

.. tip::

Settings that apply to the entire project are configured in the Admin tab of the :term:`project home`, while settings that are version or build specific are better in the configuration file.

.. TODO there is a bit of handwaving about whether you're commiting and merging branches here, we might need to be a bit more explicit. Or at least add a mention at this level that wherever we talk about editing, we mean on main and pushing to GH.

Using different Python versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To build your project with Python 3.8 instead of Python 3.10, edit the ``.readthedocs.yaml`` file and change the Python version to 3.8 like this:
To build your project with Python 3.8 instead of the latest Python version, edit the ``.readthedocs.yaml`` file and change the Python version to 3.8 like this:

.. code-block:: yaml
:caption: .readthedocs.yaml
Expand Down Expand Up @@ -304,7 +294,7 @@ After you commit these changes, go back to your project home,
navigate to the "Builds" page, and open the new build that just started.
You will notice that one of the lines contains ``python -mvirtualenv``:
if you click on it, you will see the full output of the corresponding command,
stating that it used Python 3.8.6, the latest version of Python 3.8 to create the virtual environment.
stating that it used Python 3.8.6, the latest version of Python 3.8, to create the virtual environment.

.. figure:: /_static/images/tutorial/build-python3.8.png
:width: 80%
Expand Down Expand Up @@ -338,7 +328,7 @@ and you will see several warnings:
To spot these warnings more easily and help you to address them,
add the ``sphinx.fail_on_warning`` option to your Read the Docs configuration file.

To fail on warnings to your Read the Docs project, edit the ``.readthedocs.yaml`` file in your project add the three lines of ``sphinx`` configuration below, and commit the file:
To fail on warnings to your Read the Docs project, edit the ``.readthedocs.yaml`` file in your project, add the three lines of ``sphinx`` configuration below, and commit the file:

.. code-block:: yaml
:caption: .readthedocs.yaml
Expand All @@ -359,16 +349,16 @@ To fail on warnings to your Read the Docs project, edit the ``.readthedocs.yaml`
configuration: docs/source/conf.py
fail_on_warning: true

If you navigate to your "Builds" page, you will see a ``Failed`` build, which is expected because we've configured Sphinx fail on the warnings we saw above.
If you navigate to your "Builds" page, you will see a ``Failed`` build, which is expected because we've configured Sphinx to fail on warnings and several warnings were encountered during the build.

To learn how to fix the warnings, see `Install Python Dependencies <#installing-python-dependencies>`_.
To learn how to fix these warnings, see the next section.

Installing Python dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The reason :py:mod:`sphinx:sphinx.ext.autosummary` and :py:mod:`sphinx:sphinx.ext.autodoc` fail to import the `code above <#making-build-warnings-more-visible>`_, is because the ``lumache`` module is not installed.
The reason :py:mod:`sphinx:sphinx.ext.autosummary` and :py:mod:`sphinx:sphinx.ext.autodoc` fail to import the :ref:`tutorial/index:making build warnings more visible`, is because the ``lumache`` module is not installed.

Luckily, you can specify those installation requirements in ``.readthedocs.yaml``.
You will need to specify those installation requirements in ``.readthedocs.yaml``.

To install your project dependencies and make your code available to Sphinx,
edit ``.readthedocs.yaml``, add the ``python.install`` section and commit it:
Expand Down Expand Up @@ -430,22 +420,22 @@ that points to the default branch of your version control system
(``main`` in the case of this tutorial),
and that's why the URLs of your HTML documentation contain the string ``/latest/``.

Creating a new version
~~~~~~~~~~~~~~~~~~~~~~
Creating a new version of your documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Let's say you want to create a ``1.0`` version of your code,
with a corresponding ``1.0`` version of the documentation.
For that, first navigate to your GitHub repository, click on the branch selector,
type ``1.0.x``, and click on "Create branch: 1.0.x from 'main'"
(more information `on their documentation`__).
Read the Docs automatically creates documentation versions from GitHub branches and tags that :ref:`follows some rules <versions:how we envision versions working>` about looking like version numbers, such as ``1.0``, ``2.0.3`` or ``4.x``.

__ https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository
To create version ``1.0`` of your code, and consequently of your documentation:

#. Navigate to your GitHub repository, click the branch selector, type ``1.0.x``, and click "Create branch: 1.0.x from 'main'" (more information `in the GitHub documentation`__).

Next, go to your :term:`project home`, click on the :guilabel:`Versions` button,
and under "Active Versions" you will see two entries:
#. Check that now have version ``1.0.x`` in your :term:`project home`, click on the :guilabel:`Versions` button, and under "Active Versions" you will see two entries:

- The ``latest`` version, pointing to the ``main`` branch.
- A new ``stable`` version, pointing to the ``origin/1.0.x`` branch.

__ https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository

- The ``latest`` version, pointing to the ``main`` branch.
- A new ``stable`` version, pointing to the ``origin/1.0.x`` branch.

.. figure:: /_static/images/tutorial/active-versions.png
:width: 80%
Expand All @@ -454,30 +444,18 @@ and under "Active Versions" you will see two entries:

List of active versions of the project

Right after you created your branch,
Read the Docs created a new special version called ``stable`` pointing to it,
and started building it. When the build finishes,
the ``stable`` version will be listed in the :term:`flyout menu`
and your readers will be able to choose it.
When you created your branch,
Read the Docs created a new special version called ``stable`` pointing to it. When it's built it will be listed in the :term:`flyout menu`.

.. note::

Read the Docs :ref:`follows some rules <versions:how we envision versions working>`
to decide whether to create a ``stable`` version pointing to your new branch or tag.
To simplify, it will check if the name resembles a version number
like ``1.0``, ``2.0.3`` or ``4.x``.
Setting stable as the default
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Now you might want to set ``stable`` as the *default version*,
To set ``stable`` as the *default version*,
rather than ``latest``,
so that users see the ``stable`` documentation
when they visit the :term:`root URL` of your documentation
(while still being able to change the version in the flyout menu).
when they visit the :term:`root URL` of your documentation:

For that, go to the :guilabel:`Settings` link
under the :guilabel:`⚙ Admin` menu of your project home,
choose ``stable`` in the "Default version*" dropdown,
and hit :guilabel:`Save` at the bottom.
Done!
#. In the the :guilabel:`⚙ Admin` menu of your project home, go to the :guilabel:`Settings` link, choose ``stable`` in the "Default version*" dropdown, and hit :guilabel:`Save` at the bottom.

Modifying versions
~~~~~~~~~~~~~~~~~~
Expand All @@ -494,20 +472,15 @@ version, which will always point to the ``1.0.x`` branch of your repository.

List of inactive versions of the project

Let's activate the ``1.0.x`` version.
For that, go to the "Versions" on your :term:`project home`,
locate ``1.0.x`` under "Activate a version",
and click on the :guilabel:`Activate` button.
This will take you to a new page with two checkboxes,
"Active" and "Hidden". Check only "Active",
and click :guilabel:`Save`.
To activate the ``1.0.x`` version:

#. On your :term:`project home`, go to the "Versions", locate ``1.0.x`` under "Activate a version", and click the :guilabel:`Activate` button.

After you do this, ``1.0.x`` will appear on the "Active Versions" section,
and a new build will be triggered for it.
#. On the "Activate" page with "Active" and "Hidden" checkboxes, check only "Active" and click :guilabel:`Save`.

.. note::

You can read more about :ref:`hidden versions <versions:hidden>`
Read more about :ref:`hidden versions <versions:hidden>`
in our documentation.

.. "Show a warning for old versions" feature is not available anymore.
Expand Down Expand Up @@ -545,32 +518,31 @@ and a new build will be triggered for it.

Warning for old versions

Getting insights from your projects
-----------------------------------
Getting project insights
------------------------

Once your project is up and running, you will probably want to understand
how readers are using your documentation, addressing some common questions like:

- what pages are the most visited pages?
- what search terms are the most frequently used?
- are readers finding what they look for?
- what are the most visited pages?
- what are the most frequently used search terms?
- are readers finding what they are looking for?

Read the Docs has traffic and search analytics tools to help you find answers to these questions.

Read the Docs offers you some analytics tools to find out the answers.
Understanding traffic analytics
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Browsing traffic analytics
~~~~~~~~~~~~~~~~~~~~~~~~~~
The Traffic Analytics view gives you a simple overview of how your readers browse your documentation. It respects visitor privacy by not storing identifying information about your them.

The :doc:`/analytics` view shows the top viewed documentation pages of the past 30 days,
plus a visualization of the daily views during that period.
To generate some artificial views on your newly created project,
you can first click around the different pages of your project,
which will be accounted immediately for the current day statistics.

To see the Traffic Analytics view, go back the :term:`project page` again,
click on the :guilabel:`⚙ Admin` button,
and then click on the :guilabel:`Traffic Analytics` section.
click the :guilabel:`⚙ Admin` button,
and then click the :guilabel:`Traffic Analytics` section.
You will see the list of pages in descending order of visits,
as well as a plot similar to the one below.
and a similar visualization to this one:

.. figure:: /_static/images/tutorial/traffic-analytics-plot.png
:width: 80%
Expand All @@ -579,32 +551,24 @@ as well as a plot similar to the one below.

Traffic Analytics plot

You can also download this data in :abbr:`CSV (Comma-Separated Values)` format for closer inspection.
To do that, scroll to the bottom of the page
and click the :guilabel:`Download all data` button.

.. note::

The Traffic Analytics view explained above gives you a simple overview
of how your readers browse your documentation. It has the advantage that
it stores no identifying information about your visitors,
and therefore it respects their privacy.
However, you might want to get more detailed data by
You can get more detailed traffic data by
:ref:`enabling Google Analytics <analytics:Enabling Google Analytics on your Project>`.
Notice though that we take some extra measures to :ref:`respect user
Notice though that Read the Docs takes extra measures to :ref:`respect user
privacy <advertising/advertising-details:analytics>`
when they visit projects that have Google Analytics enabled,
and this might reduce the number of visits counted.
which might reduce the number of visits counted.

Finally, you can also download this data for closer inspection.
To do that, scroll to the bottom of the page
and click on the :guilabel:`Download all data` button.
That will prompt you to download a :abbr:`CSV (Comma-Separated Values)` file
that you can process any way you want.

Browsing search analytics
~~~~~~~~~~~~~~~~~~~~~~~~~
Understanding search analytics
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Apart from traffic analytics, Read the Docs also offers the possibility
to inspect :doc:`what search terms your readers use </guides/search-analytics>`
on your documentation.
This can inform decisions on what areas to reinforce,
As well as traffic analytics, Read the Docs shows :doc:`what terms your readers are searching for </guides/search-analytics>`.
This can inform decisions on what areas to focus on,
or what parts of your project are less understood or more difficult to find.

To generate some artificial search statistics on the project,
Expand All @@ -613,7 +577,7 @@ type ``ingredients``, and press the :kbd:`Enter` key.
You will be redirected to the search results page, which will show two entries.

Next, go back to the :guilabel:`⚙ Admin` section of your project page,
and then click on the :guilabel:`Search Analytics` section.
and then click the :guilabel:`Search Analytics` section.
You will see a table with the most searched queries
(including the ``ingredients`` one you just typed),
how many results did each query return, and how many times it was searched.
Expand All @@ -633,30 +597,28 @@ by clicking on the :guilabel:`Download all data` button.
Where to go from here
---------------------

This is the end of the tutorial. You started by forking a GitHub repository
and importing it on Read the Docs, building its HTML documentation,
and then went through a series of steps to customize the build process,
tweak the project configuration, and add new versions.
This is the end of the tutorial. You have accomplished a lot:

#. Forked a GitHub repository.
#. Connected it to Read the Docs.
#. Built its HTML documentation.
#. Customized the build process.
#. Added new documentation versions.
#. Browsed the project analytics.

Nice work!

Here you have some resources to continue learning about documentation
Here are some resources to help you continue learning about documentation
and Read the Docs:

- You can learn more about the functionality of the platform
by going over our :doc:`features </reference/features>` page.
- To make the most of the documentation generators that are supported,
you can read the :doc:`Sphinx tutorial <sphinx:tutorial/index>`
or the `MkDocs User Guide <https://www.mkdocs.org/user-guide/>`_.
- Display example projects and read the source code in :doc:`/examples`.
- Whether you are a documentation author, a project administrator, a developer, or a designer,
you can follow our how-to guides that cover specific tasks,
available under :doc:`/guides/index`.
- For private project support and other enterprise features,
you can use :doc:`our commercial service </commercial/index>`
(and if in doubt, check out :doc:`/choosing-a-site`).
- Do you want to join a global community of fellow `documentarians <writethedocs:documentarians>`?
Check out `Write the Docs <https://www.writethedocs.org/>`_ and
- Learn more about the platform :doc:`features </reference/features>`.
- Learn about other supported documentation generators in the :doc:`Sphinx tutorial <sphinx:tutorial/index>` or the `MkDocs User Guide <https://www.mkdocs.org/user-guide/>`_.
- See a list of Read the Docs :doc:`/examples`.
- Learn how to do specific tasks in the :doc:`/guides/index`.
- Learn about private project support and other enterprise features
in :doc:`our commercial service </commercial/index>` and :doc:`/choosing-a-site` guide.
- Join a global community of fellow `documentarians <writethedocs:documentarians>` in `Write the Docs <https://www.writethedocs.org/>`_ and
:doc:`its Slack workspace <writethedocs:slack>`.
- Do you want to contribute to Read the Docs?
We greatly appreciate it! Check out :doc:`rtd-dev:contribute`.
- Contribute to Read the Docs in :doc:`rtd-dev:contribute`, we appreciate it!

Happy documenting!