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>

doc/advanced-topics.rst

@@ -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
 =================
 

doc/documentation.rst

@@ -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

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`__
+The with-configure-step_ example shows one way to do it which
-shows one way to do it which preserves composability; i.e. it doesn't require
+preserves composability; i.e. it doesn't require manually running `./configure`
-manually running `./configure` script when working on multiple projects at the
+script when working on multiple projects at the same time.
-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
+Yes, have a look at the topkg-jbuilder_ project for more details.
-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`__
+The dune-universe_ repository contains a snapshot of the latest versions of all
-repository contains a snapshot of the latest versions of all opam
+opam packages depending on jbuilder. It is therefore a useful reference to
-packages depending on jbuilder. It is therefore a useful reference to
+search through to find different approaches to constructing build rules.
-search through to find different approaches to constructing build
+
-rules.
+.. _dune-universe: https://github.com/dune-universe/dune-universe

doc/jbuild.rst

@@ -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
+tools such as ``pkg-config``, however it integrates easily with configurator_ by
-<https://github.com/janestreet/configurator>`__ by using ``(c_flags (:include
+using ``(c_flags (:include ...))`` and ``(c_library_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:
 

doc/project-layout-specification.rst

@@ -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.

doc/terminology.rst

@@ -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

doc/usage.rst

@@ -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
+in order to setup cross compilation. See :ref:`advanced-cross-compilation`
-information.
+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