Fix sphinx warnings (#835)
* Fix markup * Fix links * Fix references * Fix leading space * Add missing code markup Signed-off-by: Etienne Millon <etienne@cryptosense.com>
This commit is contained in:
parent
d708cc714d
commit
4ab291d0b8
|
@ -95,6 +95,8 @@ set of predicates:
|
|||
it is linked as part of a driver or meant to add a ``-ppx`` argument
|
||||
to the compiler, choose the former behavior
|
||||
|
||||
.. _advanced-cross-compilation:
|
||||
|
||||
Cross Compilation
|
||||
=================
|
||||
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
.. _documentation:
|
||||
|
||||
************************
|
||||
Generating Documentation
|
||||
************************
|
||||
|
@ -53,7 +55,7 @@ belong to any particular package. But the generated html will still be found in
|
|||
.. _doc-stanza:
|
||||
|
||||
Documentation Stanza
|
||||
===================
|
||||
====================
|
||||
|
||||
Documentation pages will be automatically generated for from .ml and .mli files
|
||||
that include ocamldoc fragments. Additional manual pages may be attached to
|
||||
|
|
24
doc/faq.rst
24
doc/faq.rst
|
@ -20,22 +20,24 @@ convenience, for the following reasons:
|
|||
How to add a configure step to a jbuilder project?
|
||||
==================================================
|
||||
|
||||
`example/sample-projects/with-configure-step https://github.com/ocaml/dune/tree/master/example/sample-projects/with-configure-step`__
|
||||
shows one way to do it which preserves composability; i.e. it doesn't require
|
||||
manually running `./configure` script when working on multiple projects at the
|
||||
same time.
|
||||
The with-configure-step_ example shows one way to do it which
|
||||
preserves composability; i.e. it doesn't require manually running `./configure`
|
||||
script when working on multiple projects at the same time.
|
||||
|
||||
.. _with-configure-step: https://github.com/ocaml/dune/tree/master/example/sample-projects/with-configure-step
|
||||
|
||||
Can I use topkg with jbuilder?
|
||||
==============================
|
||||
|
||||
Yes, have a look at the `topkg-jbuilder https://github.com/samoht/topkg-jbuilder`__ project for
|
||||
more details.
|
||||
Yes, have a look at the topkg-jbuilder_ project for more details.
|
||||
|
||||
.. _topkg-jbuilder: https://github.com/samoht/topkg-jbuilder
|
||||
|
||||
here can I find some examples of projects using Jbuilder?
|
||||
=========================================================
|
||||
|
||||
The `dune-universe https://github.com/dune-universe/dune-universe`__
|
||||
repository contains a snapshot of the latest versions of all opam
|
||||
packages depending on jbuilder. It is therefore a useful reference to
|
||||
search through to find different approaches to constructing build
|
||||
rules.
|
||||
The dune-universe_ repository contains a snapshot of the latest versions of all
|
||||
opam packages depending on jbuilder. It is therefore a useful reference to
|
||||
search through to find different approaches to constructing build rules.
|
||||
|
||||
.. _dune-universe: https://github.com/dune-universe/dune-universe
|
||||
|
|
|
@ -184,9 +184,10 @@ modules you want.
|
|||
overlap with libraries that are present in the workspace
|
||||
|
||||
Note that when binding C libraries, Jbuilder doesn't provide special support for
|
||||
tools such as ``pkg-config``, however it integrates easily with `configurator
|
||||
<https://github.com/janestreet/configurator>`__ by using ``(c_flags (:include
|
||||
...))`` and ``(c_library_flags (:include ...))``.
|
||||
tools such as ``pkg-config``, however it integrates easily with configurator_ by
|
||||
using ``(c_flags (:include ...))`` and ``(c_library_flags (:include ...))``.
|
||||
|
||||
.. _configurator: https://github.com/janestreet/configurator
|
||||
|
||||
executable
|
||||
----------
|
||||
|
@ -640,6 +641,8 @@ where ``<destination>`` describe how the file will be installed. For
|
|||
instance, to install a file ``mylib.el`` as
|
||||
``emacs/site-lisp/mylib.el`` in the ``share_root`` section:
|
||||
|
||||
.. code:: scheme
|
||||
|
||||
(install
|
||||
((section share_root)
|
||||
(files ((mylib.el as emacs/site-lisp/mylib.el)))))
|
||||
|
@ -711,6 +714,8 @@ With this jbuild file, running jbuilder as follow will replace the
|
|||
|
||||
$ jbuilder build @runtest --auto-promote
|
||||
|
||||
.. _jbuild-env:
|
||||
|
||||
env
|
||||
---
|
||||
|
||||
|
@ -732,6 +737,8 @@ directory. You can use ``_`` to match any build profile.
|
|||
Currently ``<settings>`` can be any OCaml flags field, see `OCaml
|
||||
flags`_ for more details.
|
||||
|
||||
.. _jbuild-ignored_subdirs:
|
||||
|
||||
ignored_subdirs
|
||||
---------------
|
||||
|
||||
|
@ -791,7 +798,7 @@ Jbuilder supports the following variables:
|
|||
the toplevel directory of your project and as long as you have at
|
||||
least one ``<package>.opam`` file there, ``SCOPE_ROOT`` is
|
||||
independent of the workspace configuration
|
||||
- ``CC`` is the C compiler command line (list made of the compiler
|
||||
- ``CC`` is the C compiler command line (list made of the compiler
|
||||
name followed by its flags) that was used to compile OCaml in the
|
||||
current build context
|
||||
- ``CXX`` is the C++ compiler command line being used in the
|
||||
|
@ -806,7 +813,7 @@ Jbuilder supports the following variables:
|
|||
- ``ARCH_SIXTYFOUR`` is ``true`` if using a compiler targeting a
|
||||
64 bit architecture and ``false`` otherwise
|
||||
- ``null`` is ``/dev/null`` on Unix or ``nul`` on Windows
|
||||
- ``ext_obj``, ``ext_asm``, ``ext_lib``, ``ext_dll`` and ``ext_exe``
|
||||
- ``ext_obj``, ``ext_asm``, ``ext_lib``, ``ext_dll`` and ``ext_exe``
|
||||
are the file extension used for various artifacts
|
||||
- ``ocaml-config:v`` for every variable ``v`` in the output of
|
||||
``ocamlc -config``. Note that output Jbuilder processes the output
|
||||
|
@ -1152,6 +1159,8 @@ follows:
|
|||
|
||||
(flags (:standard <my options>))
|
||||
|
||||
.. _jbuild-jsoo:
|
||||
|
||||
js_of_ocaml
|
||||
-----------
|
||||
|
||||
|
@ -1166,7 +1175,7 @@ using ``(js_of_ocaml (<js_of_ocaml-options>))``.
|
|||
- ``(javascript_files (<files-list>))`` to specify ``js_of_ocaml`` JavaScript
|
||||
runtime files.
|
||||
|
||||
=<flags>= is specified in the `Ordered set language`_.
|
||||
``<flags>`` is specified in the `Ordered set language`_.
|
||||
|
||||
The default value for ``(flags ...)`` depends on whether ``--dev`` is passed to
|
||||
Jbuilder. ``--dev`` will enable sourcemap and the pretty JavaScript output.
|
||||
|
@ -1191,7 +1200,7 @@ automatically handled by Jbuilder.
|
|||
The DSL is currently quite limited, so if you want to do something complicated
|
||||
it is recommended to write a small OCaml program and use the DSL to invoke it.
|
||||
You can use `shexp <https://github.com/janestreet/shexp>`__ to write portable
|
||||
scripts or `Configurator`_ for configuration related tasks.
|
||||
scripts or configurator_ for configuration related tasks.
|
||||
|
||||
The following constructions are available:
|
||||
|
||||
|
|
|
@ -225,4 +225,4 @@ jbuild-ignore (deprecated)
|
|||
==========================
|
||||
|
||||
``jbuild-ignore`` files are deprecated and replaced by
|
||||
`ignored_subdirs`_ stanzas in ``dune`` files.
|
||||
:ref:`jbuild-ignored_subdirs` stanzas in ``dune`` files.
|
||||
|
|
|
@ -53,14 +53,14 @@ 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
|
||||
documentation. See :ref:`documentation` for details.
|
||||
|
||||
- **environment**: in Jbuilder, each directory has an environment
|
||||
attached to it. The environment determines the default values of
|
||||
various parameters, such as the compilation flags. Inside a scope,
|
||||
each directory inherit the environment from its parent. At the root
|
||||
of every scope, a default environment is used. At any point, the
|
||||
environment can be altered using an `env`_ stanza.
|
||||
environment can be altered using an :ref:`jbuild-env` stanza.
|
||||
|
||||
- **build profile**: a global setting that influence various
|
||||
defaults. It can be set from the command line using ``--profile
|
||||
|
|
|
@ -59,7 +59,7 @@ in ancestor directories. For instance ``jbuild-workspace.dev``. If such a file
|
|||
is found, it will mark the root of the workspace. ``jbuilder`` will however not
|
||||
read its contents.
|
||||
|
||||
The rationale for this rule is that it is good practice to have a
|
||||
The rationale for this rule is that it is good practice to have a
|
||||
``jbuild-workspace.dev`` file at the root of your project.
|
||||
|
||||
For quick experiments, simply do this to mark the root:
|
||||
|
@ -391,15 +391,15 @@ context or can be the description of an opam switch, as follows:
|
|||
run which is usually ``~/.opam``
|
||||
|
||||
- ``(merlin)`` instructs Jbuilder to use this build context for
|
||||
merlin
|
||||
merlin
|
||||
|
||||
- ``(profile <profile>)`` to set a different profile for a build
|
||||
context. This has precedence over the command line option
|
||||
``--profile``
|
||||
|
||||
Both ``(default ...)`` and ``(opam ...)`` accept a ``targets`` field
|
||||
in order to setup cross compilation. See `Cross Compilation`_ for more
|
||||
information.
|
||||
in order to setup cross compilation. See :ref:`advanced-cross-compilation`
|
||||
for more information.
|
||||
|
||||
Merlin reads compilation artifacts and it can only read the
|
||||
compilation artifacts of a single context. Usually, you should use
|
||||
|
@ -476,7 +476,7 @@ And that if your project contains several packages, then all the
|
|||
package names must be prefixed by the shortest one.
|
||||
|
||||
Watermarking
|
||||
~~~~~~~~~~~~
|
||||
============
|
||||
|
||||
One of the feature topkg provides is watermarking; it replaces various
|
||||
strings of the form ``%%ID%%`` in all files of your project before
|
||||
|
@ -498,7 +498,7 @@ watermarks when the package is pinned by the user. To help with this,
|
|||
jbuilder provides the ``subst`` sub-command.
|
||||
|
||||
jbuilder subst
|
||||
~~~~~~~~~~~~~~
|
||||
==============
|
||||
|
||||
``jbuilder subst`` performs the same substitution ``topkg`` does with
|
||||
the default configuration. i.e. calling ``jbuilder subst`` at the root
|
||||
|
|
Loading…
Reference in New Issue