diff --git a/doc/api-doc.rst b/doc/api-doc.rst new file mode 100644 index 00000000..ac6aa63c --- /dev/null +++ b/doc/api-doc.rst @@ -0,0 +1,45 @@ +***************** +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 developping 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/index.rst b/doc/index.rst index 1c59d6e7..0a6ad217 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -14,5 +14,6 @@ Welcome to jbuilder's documentation! terminology project-layout-specification jbuild + api-doc usage advanced-topics diff --git a/doc/terminology.rst b/doc/terminology.rst index be2e6481..3fa9191b 100644 --- a/doc/terminology.rst +++ b/doc/terminology.rst @@ -40,3 +40,5 @@ Terminology - ``runtest`` which runs user defined tests - ``install`` which depends on everything that should be installed + - ``doc`` which depends on the generated HTML + documentation. See :ref:`apidoc` for details