diff --git a/doc/api-doc.rst b/doc/api-doc.rst deleted file mode 100644 index 70eb42f0..00000000 --- a/doc/api-doc.rst +++ /dev/null @@ -1,45 +0,0 @@ -***************** -API documentation -***************** - -Jbuilder supports generating API documentation for libraries using the -`odoc tool `__ 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 -`_. - -Generated pages -=============== - -Jbuilder stores the generated HTML pages in -``_build//_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 -``.mld``, Jbuilder will generate the library index from this -file. ```` 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. diff --git a/doc/documentation.rst b/doc/documentation.rst index 8b0539d9..d8a8b755 100644 --- a/doc/documentation.rst +++ b/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 `_. + +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/``. -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 diff --git a/doc/index.rst b/doc/index.rst index c7605de5..32e11241 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -16,6 +16,5 @@ Welcome to jbuilder's documentation! jbuild tests documentation - api-doc usage advanced-topics