From 70ee9bcd6accc8e67288e37d8976e43094ea9c74 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= <hello@juanlu.space>
Date: Tue, 25 May 2021 10:56:22 +0200
Subject: [PATCH] Tutorial link in front page, audience, objectives, and
 prerequisites

---
 doc/_templates/index.html | 12 +++++++-----
 doc/contents.rst          |  1 +
 doc/tutorial/index.rst    | 25 +++++++++++++++++++++++++
 3 files changed, 33 insertions(+), 5 deletions(-)
 create mode 100644 doc/tutorial/index.rst

diff --git a/doc/_templates/index.html b/doc/_templates/index.html
index a37579c29..a688d17c1 100644
--- a/doc/_templates/index.html
+++ b/doc/_templates/index.html
@@ -52,23 +52,25 @@
         <p class="biglink"><a class="biglink" href="{{ pathto("usage/quickstart") }}">{%trans%}First steps with Sphinx{%endtrans%}</a><br/>
            <span class="linkdescr">{%trans%}overview of basic tasks{%endtrans%}</span></p>
       </td><td>
-        {%- if hasdoc('search') %}<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{%trans%}Search page{%endtrans%}</a><br/>
-           <span class="linkdescr">{%trans%}search the documentation{%endtrans%}</span></p>{%- endif %}
+        <p class="biglink"><a class="biglink" href="{{ pathto("tutorial/index") }}">{%trans%}Tutorial{%endtrans%}</a><br/>
+           <span class="linkdescr">{%trans%}beginners tutorial{%endtrans%}</span></p>
       </td>
     </tr><tr>
       <td>
         <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{%trans%}Contents{%endtrans%}</a><br/>
            <span class="linkdescr">{%trans%}for a complete overview{%endtrans%}</span></p>
       </td><td>
-        {%- if hasdoc('genindex') %}<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{%trans%}General Index{%endtrans%}</a><br/>
-           <span class="linkdescr">{%trans%}all functions, classes, terms{%endtrans%}</span></p>{%- endif %}
+        {%- if hasdoc('search') %}<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{%trans%}Search page{%endtrans%}</a><br/>
+           <span class="linkdescr">{%trans%}search the documentation{%endtrans%}</span></p>{%- endif %}
       </td>
     </tr><tr>
       <td>
         <p class="biglink"><a class="biglink" href="{{ pathto("changes") }}">{%trans%}Changes{%endtrans%}</a><br/>
            <span class="linkdescr">{%trans%}release history{%endtrans%}</span></p>
       </td><td>
-      </td>
+        {%- if hasdoc('genindex') %}<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{%trans%}General Index{%endtrans%}</a><br/>
+           <span class="linkdescr">{%trans%}all functions, classes, terms{%endtrans%}</span></p>{%- endif %}
+      </td><td>
     </tr>
   </table>
 
diff --git a/doc/contents.rst b/doc/contents.rst
index eb6946292..21a27e233 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -7,6 +7,7 @@ Sphinx documentation contents
    :maxdepth: 2
 
    usage/index
+   tutorial/index
    development/index
    man/index
 
diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst
new file mode 100644
index 000000000..81845c559
--- /dev/null
+++ b/doc/tutorial/index.rst
@@ -0,0 +1,25 @@
+.. _tutorial:
+
+===============
+Sphinx tutorial
+===============
+
+In this tutorial you will build a simple documentation project using Sphinx,
+and view it in your web browser as HTML.
+We will include narrative, handwritten documentation,
+as well as autogenerated API documentation.
+
+The tutorial is aimed towards people willing to learn
+the fundamentals of Sphinx,
+how projects are created and structured,
+and how to contribute to an existing project.
+To showcase Sphinx automatic documentation generation capabilities
+we will use Python, which is the default :term:`domain`:
+even though several other languages are supported,
+they all work in a similar way.
+
+To follow the tutorial you will need a working Python installation for development.
+We will use *Python virtual environments* to create our project,
+you can read more about them in the `Python Packaging User Guide`_.
+
+.. _Python Packaging User Guide: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment