docs, user: Fix faq menu rendering glitch

As the toctree for the faq was included multiple times in index file,
the associated menu entry in the sidebar was not properly rendered.

In order to workaround the issue, ensure faq toctree is included once
in the index file and add reference to faq page in Getting started
top level section.

Also as faq subsection entries are no longer included in the sidebar
menu, display a local toctree at the top of the faq page.

Closes T3657

docs/faq/index.rst

@@ -3,6 +3,11 @@
 Frequently Asked Questions
 **************************
 
+.. contents::
+   :depth: 3
+   :local:
+..
+
 .. _faq_prerequisites:
 
 Prerequisites for code contributions

docs/index.rst

@@ -10,6 +10,7 @@ Getting started
   software stack in less than 5 minutes, or
 * :ref:`developer-setup` → get a working development setup that allows to hack
   on the Software Heritage software stack
+* :ref:`faq`
 
 Contributing
 ------------
@@ -49,14 +50,6 @@ Tutorials
 * :ref:`Add a new swh package <tutorial-new-package>`
 * :ref:`doc-contribution`
 
-Frequently Asked Questions
---------------------------
-
-.. toctree::
-   :maxdepth: 2
-
-   faq/index
-
 Roadmap
 -------
 

user/faq/index.rst

@@ -3,6 +3,11 @@
 Frequently Asked Questions
 **************************
 
+.. contents::
+   :depth: 3
+   :local:
+..
+
 .. _faq_roadmap:
 
 Roadmap

user/index.rst

@@ -10,22 +10,13 @@ Software Heritage User documentation
 
 Getting started
 ---------------
-
-...
+* :ref:`faq`
 
 Tutorials
 ---------
 
 ...
 
-Frequently Asked Questions
----------------------------
-
-.. toctree::
-   :maxdepth: 2
-
-   faq/index
-
 
 Indices and tables
 ==================

[Phabricator Migration user]

Some references in the commit message have been migrated:

• T3657 is now #3657 (closed)