Remove old api-doc page
And incorporate it into the new documentation page
This commit is contained in:
parent
2e636ef43e
commit
95a617ec63
|
@ -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.
|
|
|
@ -2,6 +2,9 @@
|
||||||
Generating Documentation
|
Generating Documentation
|
||||||
************************
|
************************
|
||||||
|
|
||||||
|
Prerequisites
|
||||||
|
=============
|
||||||
|
|
||||||
Documentation in jbuilder is done courtesy of the odoc_ tool. Therefore, to
|
Documentation in jbuilder is done courtesy of the odoc_ tool. Therefore, to
|
||||||
generate documentation in jbuilder, you will need to install this tool. This
|
generate documentation in jbuilder, you will need to install this tool. This
|
||||||
should likely be done with opam:
|
should likely be done with opam:
|
||||||
|
@ -10,6 +13,16 @@ should likely be done with opam:
|
||||||
|
|
||||||
$ opam install odoc
|
$ 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
|
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
|
belong to any particular package. But the generated html will still be found in
|
||||||
``_build/default/_doc/_html/<library>``.
|
``_build/default/_doc/_html/<library>``.
|
||||||
|
|
||||||
Attaching Documentation
|
.. _doc-stanza:
|
||||||
=======================
|
|
||||||
|
Docmentation Stanza
|
||||||
|
===================
|
||||||
|
|
||||||
Documentation pages will be automatically generated for from .ml and .mli files
|
Documentation pages will be automatically generated for from .ml and .mli files
|
||||||
that include ocamldoc fragments. Additional manual pages may be attached to
|
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
|
.. code-block:: lisp
|
||||||
|
|
||||||
|
|
|
@ -16,6 +16,5 @@ Welcome to jbuilder's documentation!
|
||||||
jbuild
|
jbuild
|
||||||
tests
|
tests
|
||||||
documentation
|
documentation
|
||||||
api-doc
|
|
||||||
usage
|
usage
|
||||||
advanced-topics
|
advanced-topics
|
||||||
|
|
Loading…
Reference in New Issue