diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index d84b7d442..46810c400 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -34,12 +34,12 @@ since you will use *Python virtual environments* to create the project. Getting started --------------- -Setting up our project and development environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Setting up your project and development environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -On a new directory, +In a new directory, create a file called ``README.rst`` -with the following contents: +with the following content. .. code-block:: rest @@ -82,16 +82,16 @@ If you see a similar output, you are on the right path! Creating the documentation layout ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Then, from the command line, +Then from the command line, run the following command: .. code-block:: bash (.venv) $ sphinx-quickstart docs -This will present you a series of questions +This will present to you a series of questions required to create the basic directory and configuration layout for your project -inside the `docs/` folder. +inside the ``docs`` folder. To proceed, introduce these answers: - ``> Separate source and build directories (y/n) [n]``: Write "``y``" (without quotes) @@ -106,7 +106,9 @@ To proceed, introduce these answers: and press :kbd:`Enter`. After the last question, -you will see the new ``docs`` directory with some content:: +you will see the new ``docs`` directory with the following content. + +.. code-block:: text docs/ ├── build @@ -168,7 +170,7 @@ and it gets rendered as the front page of our HTML documentation. It is written in reStructuredText, a powerful markup language. -Modify the file like follows: +Modify the file as follows. .. code-block:: rest @@ -192,9 +194,9 @@ This showcases several features of the reStructuredText syntax, including: - an **inline external link**, - and a ``note`` **admonition**. -Now, to render it with the new content, +Now to render it with the new content, you can use the ``sphinx-build`` command as before, -or leverage the convenience script like this: +or leverage the convenience script as follows. .. code-block:: bash diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst index 985f7fa34..69468a4f2 100644 --- a/doc/usage/installation.rst +++ b/doc/usage/installation.rst @@ -190,8 +190,8 @@ Using virtual environments When installing Sphinx using pip, it is highly recommended to use *virtual environments*, -which isolate the Installation -and remove the need to use administrator privileges. +which isolate the installed packages from the system packages, +thus removing the need to use administrator privileges. To create a virtual environment in the ``.venv`` directory, use the following command. @@ -205,8 +205,11 @@ You can read more about them in the `Python Packaging User Guide`_. .. warning:: - Note like in some Linux distributions like Debian and Ubuntu - this might require an extra installation step:: + Note that in some Linux distributions, such as Debian and Ubuntu, + this might require an extra installation step as follows. + + .. code-block:: bash + $ apt-get install python3-venv