Generating documentation: clarify the explanation of index.mld (#4146)

* [minor] typo
* reorder content: explain the index.mld status in the 'Generating documentation' page
* explicitly recommend using an index.mld file

Signed-off-by: Gabriel Scherer <gabriel.scherer@gmail.com>

doc/documentation.rst

@@ -52,11 +52,12 @@ But this libraries will not be in the main html listing above, since they do not
 belong to any particular package. But the generated html will still be found in
 ``_build/default/_doc/_html/<library>``.
 
-Examples
---------
 
-This stanza use attach all the .mld files in the current directory in a project
-with a single package.
+documentation stanza: Examples
+------------------------------
+
+The :ref:`documentation-stanza` stanza will attach all the .mld files
+in the current directory in a project with a single package.
 
 .. code-block:: lisp
 
@@ -79,6 +80,24 @@ directory to the inferred package:
    (documentation
     (mld_files :standard \ wip))
 
+All mld files attached to a package will be included in the generated
+``.install`` file for that package, and hence will be installed by opam.
+
+Package entry page
+------------------
+
+The ``index.mld`` file (specified as ``index`` in ``mld_files``) is
+treated specially by dune. This will be the file used to generate the
+entry page for the package, linked from the main package listing.
+
+To generate pleasant documentation, we recommend writing an
+``index.mld`` file with at least short description of your package,
+and possibly some examples.
+
+If you do not write your own ``index.mld`` file, dune will generate
+one with the entry modules for your package. But this generated file
+will not be installed.
+
 .. _odoc-options:
 
 Passing options to Odoc

doc/dune-files.rst

@@ -1098,14 +1098,7 @@ Where ``<optional-fields>`` are:
   names that are attached to the package. Where ``:standard`` refers to all the
   ``.mld`` files in the stanza's directory.
 
-The ``index.mld`` file (specified as ``index`` in ``mld_files``) is treated
-specially by dune. This will be the file used to generate the entry page for the
-package. This is the page that will be linked from the main package listing. If
-you omit writing an ``index.mld``, dune will generate one with the entry modules
-for your package. But this generated will not be installed.
-
-All mld files attached to a package will be included in the generated
-``.install`` file for that package, and hence will be installed by opam.
+For more information, see :ref:`documentation`.
 
 .. _alias-stanza: