Remove old api-doc page

And incorporate it into the new documentation page

doc/api-doc.rst

@@ -1,45 +0,0 @@
-*****************
-API documentation
-*****************
-
-Jbuilder supports generating API documentation for libraries using the
-`odoc tool <https://github.com/ocaml-doc/odoc>`__ in HTML format.
-
-For this to work you need to have odoc installed and have
-documentation comments in your OCaml source files following the syntax
-described in the the section ``Text formatting`` of the `OCaml manual
-<http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html>`_.
-
-Generated pages
-===============
-
-Jbuilder stores the generated HTML pages in
-``_build/<context>/_doc``. It creates one sub-directory per public
-library and generates an ``index.html`` file in each sub-directory.
-
-The documentation is never installed on the system by Jbuilder. It is
-meant to be read locally while developing and then published on the
-www when releasing packages.
-
-Building the documentation
-==========================
-
-To build the documentaion, you can simply use the ``doc`` alias, which
-depends on the generated HTML pages for all the public libraries.
-
-For instance:
-
-.. code:: bash
-
-    $ jbuilder build @doc
-
-Custom library indexes
-======================
-
-If the directory where a library lives contains a file named
-``<lib-name>.mld``, Jbuilder will generate the library index from this
-file. ``<lib-name>`` is what you put in the ``(name ...)`` field of the
-library's jbuild file.
-
-Such a file must contains text using the same syntax as ocamldoc
-comments.

doc/documentation.rst

@@ -2,6 +2,9 @@
 Generating Documentation
 ************************
 
+Prerequisites
+=============
+
 Documentation in jbuilder is done courtesy of the odoc_ tool. Therefore, to
 generate documentation in jbuilder, you will need to install this tool. This
 should likely be done with opam:
@@ -10,6 +13,16 @@ should likely be done with opam:
 
   $ opam install odoc
 
+Writing Documentation
+=====================
+
+Documentation comments will be automatically extracted from your OCaml source
+files following the syntax described in the the section ``Text formatting`` of
+the `OCaml manual <http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html>`_.
+
+Additional documentation pages may by attached to a package can be attached
+using the :ref:`doc-stanza`.
+
 Building Documentation
 ======================
 
@@ -37,12 +50,15 @@ 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>``.
 
-Attaching Documentation
-=======================
+.. _doc-stanza:
+
+Docmentation Stanza
+===================
 
 Documentation pages will be automatically generated for from .ml and .mli files
 that include ocamldoc fragments. Additional manual pages may be attached to
-packages using the ``documentation`` stanza.
+packages using the ``documentation`` stanza. These .mld files must contain text
+in the same syntax as ocamldoc comments.
 
 .. code-block:: lisp
 

doc/index.rst

@@ -16,6 +16,5 @@ Welcome to jbuilder's documentation!
    jbuild
    tests
    documentation
-   api-doc
    usage
    advanced-topics