doc: use a hierarchy of index pages

doc/advanced/index.rst

@@ -0,0 +1,14 @@
+Advanced Topics
+===============
+
+These documents describe some advanced or very specific features of Dune.
+
+.. toctree::
+   :maxdepth: 1
+
+   findlib-dynamic
+   profiling-dune
+   package-version
+   ocaml-syntax
+   variables-artifacts
+   custom-cmxs

doc/explanation/index.rst

@@ -0,0 +1,12 @@
+Explanation
+===========
+
+These documents explain how certain feature works, or how Dune integrates with
+the rest of the OCaml ecosystem.
+
+.. toctree::
+   :maxdepth: 1
+
+   preprocessing
+   ocaml-ecosystem
+   opam-integration

doc/getting-started/index.rst

@@ -0,0 +1,13 @@
+Getting Started and Core Concepts
+=================================
+
+These documents should be the first ones read by new Dune users. They explain
+what Dune is, how it works, and how to use it.
+
+.. toctree::
+   :maxdepth: 2
+
+   ../overview
+   ../quick-start
+   ../dune-files
+   ../usage

doc/howto/index.rst

@@ -0,0 +1,21 @@
+How-to Guides
+=============
+
+These guides will help you use Dune's features in your project.
+
+.. toctree::
+   :maxdepth: 1
+
+   formatting
+   opam-file-generation
+   ../cross-compilation
+   ../foreign-code
+   ../documentation
+   ../sites
+   ../instrumentation
+   ../jsoo
+   ../melange
+   ../toplevel-integration
+   ../variants
+   ../tests
+   bundle

doc/index.rst

@@ -1,92 +1,12 @@
-.. dune documentation master file, created by
-   sphinx-quickstart on Tue Apr 11 21:24:42 2017.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to Dune's Documentation!
 ================================
 
-.. We include the titles of the pages here to make sure they are in
-   alphabetical order. Eventually we should name the files and titles
-   similarly.
-
-.. toctree::
-   :caption: Getting Started and Core Concepts
-   :maxdepth: 3
-
-   overview
-   quick-start
-   dune-files
-   usage
-
-.. toctree::
-   :caption: How-to Guides
-
-   howto/formatting
-   howto/opam-file-generation
-   cross-compilation
-   foreign-code
-   documentation
-   sites
-   instrumentation
-   jsoo
-   melange
-   toplevel-integration
-   variants
-   tests
-   howto/bundle
-
-.. toctree::
-   :caption: Reference Guides
-   :maxdepth: 3
-
-   reference/lexical-conventions
-   reference/ordered-set-language
-   reference/boolean-language
-   reference/predicate-language
-   reference/library-dependencies
-   reference/actions
-   reference/foreign
-   reference/cli
-   reference/preprocessing-spec
-   reference/packages
-   reference/findlib
-   reference/aliases
-   reference/cram
-   concepts/scopes
-   concepts/variables
-   concepts/dependency-spec
-   concepts/ocaml-flags
-   concepts/sandboxing
-   concepts/locks
-   concepts/promotion
-   concepts/package-spec
-   coq
-   caching
-   dune-libs
-   rpc
-
-.. toctree::
-   :caption: Explanations
-
-   explanation/preprocessing
-   explanation/ocaml-ecosystem
-   explanation/opam-integration
-
-.. toctree::
-   :caption: Advanced topics
-
-   advanced/findlib-dynamic
-   advanced/profiling-dune
-   advanced/package-version
-   advanced/ocaml-syntax
-   advanced/variables-artifacts
-   advanced/custom-cmxs
-
 .. toctree::
-   :caption: Miscellaneous
-   :maxdepth: 3
+   :maxdepth: 2
 
-   faq
-   goals
-   hacking
+   getting-started/index
+   howto/index
+   reference/index
+   explanation/index
+   advanced/index
+   misc/index

doc/misc/index.rst

@@ -0,0 +1,12 @@
+Miscellaneous
+=============
+
+These documents contain tidbits of info that do not fit anywhere else, and
+information about the project itself.
+
+.. toctree::
+   :maxdepth: 2
+
+   ../faq
+   ../goals
+   ../hacking

doc/reference/index.rst

@@ -0,0 +1,33 @@
+Reference Manual
+================
+
+These documents specify the various features and languages present in Dune.
+
+.. toctree::
+   :maxdepth: 2
+
+   lexical-conventions
+   ordered-set-language
+   boolean-language
+   predicate-language
+   library-dependencies
+   actions
+   foreign
+   cli
+   preprocessing-spec
+   packages
+   findlib
+   aliases
+   cram
+   ../concepts/scopes
+   ../concepts/variables
+   ../concepts/dependency-spec
+   ../concepts/ocaml-flags
+   ../concepts/sandboxing
+   ../concepts/locks
+   ../concepts/promotion
+   ../concepts/package-spec
+   ../coq
+   ../caching
+   ../dune-libs
+   ../rpc