Merge pull request #7751 from stephenfin/doc/intro-section

[doc] Remove the intro guide in favour of the quickstart guide

5 files changed, 71 insertions, 30 deletions

diff --git a/doc/contents.rst b/doc/contents.rst
index 7e87cfffa..f58655cbf 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -1,4 +1,3 @@
-
 .. _contents:
 
 Sphinx documentation contents
@@ -7,26 +6,14 @@ Sphinx documentation contents
 .. toctree::
    :maxdepth: 2
 
-   intro
-
-   usage/installation
-   usage/quickstart
-   usage/restructuredtext/index
-   usage/markdown
-   usage/configuration
-   usage/builders/index
-   usage/extensions/index
-   usage/theming
-   usage/advanced/intl
-   usage/advanced/setuptools
-   usage/advanced/websupport/index
-
+   usage/index
+   development/index
    man/index
+
    theming
    templating
    latex
    extdev/index
-   development/tutorials/index
 
    faq
    glossary
diff --git a/doc/development/index.rst b/doc/development/index.rst
new file mode 100644
index 000000000..6a3406a20
--- /dev/null
+++ b/doc/development/index.rst
@@ -0,0 +1,13 @@
+================
+Extending Sphinx
+================
+
+This guide is aimed at those wishing to develop their own extensions for
+Sphinx. Sphinx possesses significant extensibility capabilities including the
+ability to hook into almost every point of the build process.  If you simply
+wish to use Sphinx with existing extensions, refer to :doc:`/usage/index`.
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorials/index
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
new file mode 100644
index 000000000..49a4dccaa
--- /dev/null
+++ b/doc/usage/index.rst
@@ -0,0 +1,23 @@
+============
+Using Sphinx
+============
+
+This guide serves to demonstrate how one can get started with Sphinx and covers
+everything from installing Sphinx and configuring your first Sphinx project to
+using some of the advanced features Sphinx provides out-of-the-box. If you are
+looking for guidance on extending Sphinx, refer to :doc:`/development/index`.
+
+.. toctree::
+   :maxdepth: 2
+
+   quickstart
+   installation
+   restructuredtext/index
+   markdown
+   configuration
+   builders/index
+   extensions/index
+   theming
+   advanced/intl
+   advanced/setuptools
+   advanced/websupport/index
diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst
index ba93bf192..c9bef974d 100644
--- a/doc/usage/installation.rst
+++ b/doc/usage/installation.rst
@@ -12,9 +12,13 @@ Installing Sphinx
 Overview
 --------
 
-Sphinx is written in `Python`__ and supports Python 3.5+.
+Sphinx is written in `Python`__ and supports Python 3.5+. It builds upon the
+shoulders of many third-party libraries such as `Docutils`__ and `Jinja`__,
+which are installed when Sphinx is installed.
 
 __ https://docs.python-guide.org/
+__ https://docutils.sourceforge.io/
+__ https://jinja.palletsprojects.com/
 
 
 Linux
diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst
index b5462a388..8d2de021e 100644
--- a/doc/usage/quickstart.rst
+++ b/doc/usage/quickstart.rst
@@ -2,21 +2,38 @@
 Getting Started
 ===============
 
-Once Sphinx is :doc:`installed </usage/installation>`, you can proceed with
-setting up your first Sphinx project. To ease the process of getting started,
-Sphinx provides a tool, :program:`sphinx-quickstart`, which will generate a
-documentation source directory and populate it with some defaults. We're going
-to use the :program:`sphinx-quickstart` tool here, though its use is by no means
-necessary.
+Sphinx is a *documentation generator* or a tool that translates a set of plain
+text source files into various output formats, automatically producing
+cross-references, indices, etc.  That is, if you have a directory containing a
+bunch of :doc:`/usage/restructuredtext/index` or :doc:`/usage/markdown`
+documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX),
+man pages and much more.
+
+Sphinx focuses on documentation, in particular handwritten documentation,
+however, Sphinx can also be used to generate blogs, homepages and even books.
+Much of Sphinx's power comes from the richness of its default plain-text markup
+format, :doc:`reStructuredText </usage/restructuredtext/index>`, along with
+it's :doc:`significant extensibility capabilities </development/index>`.
+
+The goal of this document is to give you a quick taste of what Sphinx it is and
+how you might use it. When you're done here, you can check out the
+:doc:`installation guide </usage/installation>` followed by the intro to the
+default markup format used by Sphinx, :doc:`reStucturedText
+</usage/restructuredtext/index>`.
+
+For a great "introduction" to writing docs in general -- the whys and hows, see
+also `Write the docs`__, written by Eric Holscher.
+
+.. __: http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
 
 
 Setting up the documentation sources
 ------------------------------------
 
-The root directory of a Sphinx collection of :term:`reStructuredText` document
-sources is called the :term:`source directory`.  This directory also contains
-the Sphinx configuration file :file:`conf.py`, where you can configure all
-aspects of how Sphinx reads your sources and builds your documentation.  [#]_
+The root directory of a Sphinx collection of plain-text document sources is
+called the :term:`source directory`.  This directory also contains the Sphinx
+configuration file :file:`conf.py`, where you can configure all aspects of how
+Sphinx reads your sources and builds your documentation.  [#]_
 
 Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a
 source directory and creates a default :file:`conf.py` with the most useful
@@ -26,9 +43,6 @@ configuration values from a few questions it asks you. To use this, run:
 
    $ sphinx-quickstart
 
-There is also an automatic "API documentation" generator called
-:program:`sphinx-apidoc`; see :doc:`/man/sphinx-apidoc` for details.
-
 
 Defining document structure
 ---------------------------