doc: use console lexer for shell sessions (#9391)

* doc: use console lexer for shell sessions The `console` lexer does the right thing to represent shell sessions: it highlights the leading `$` of commands and ignores the outputs. Signed-off-by: Etienne Millon <[email protected]> * meta-documentation Signed-off-by: Etienne Millon <[email protected]> --------- Signed-off-by: Etienne Millon <[email protected]>
ocaml · Dec 7, 2023 · ab9d879 · ab9d879
1 parent ed497f7
commit ab9d879
Show file tree

Hide file tree

Showing 21 changed files with 127 additions and 125 deletions.
diff --git a/doc/concepts/package-spec.rst b/doc/concepts/package-spec.rst
@@ -129,7 +129,7 @@ For instance:
 Once ``mypackage`` is installed on the system, the user will be able
 to type the following in their shell:
 
-::
+.. code:: console
 
    $ myprog
 

diff --git a/doc/concepts/promotion.rst b/doc/concepts/promotion.rst
@@ -16,7 +16,7 @@ However, it is different for the following reason:
 - By default, it will use ``patdiff`` if it is installed. ``patdiff``
   is a better diffing program. You can install it via opam with:
 
-  .. code:: sh
+  .. code:: console
 
      $ opam install patdiff
 

diff --git a/doc/concepts/variables.rst b/doc/concepts/variables.rst
@@ -197,7 +197,7 @@ Forms that expand to a list of items, such as ``%{cc}``, ``%{deps}``,
 If there are two dependencies, ``a`` and ``b``, the produced command
 will be equivalent to the shell command:
 
-.. code:: shell
+.. code:: console
 
     $ foo "a" "b"
 
@@ -210,7 +210,7 @@ you must quote the variable:
 
 which is equivalent to the following shell command:
 
-.. code:: shell
+.. code:: console
 
     $ foo "a b"
 

diff --git a/doc/coq.rst b/doc/coq.rst
@@ -736,7 +736,7 @@ typically used by editors such as CoqIDE or Proof General to interact with Coq.
 
 The following command:
 
-.. code:: bash
+.. code:: console
 
    $ dune coq top <file> -- <args>
 
@@ -803,4 +803,4 @@ values for ``<coq_fields>``:
   ``(coq.theory (flags <flags>))`` field. 
 - ``(coqdoc_flags <flags>)``: The default flags passed to ``coqdoc``. The default
   value is ``--toc``. Values set here become the ``:standard`` value in the
-  ``(coq.theory (coqdoc_flags <flags>))`` field.
+  ``(coq.theory (coqdoc_flags <flags>))`` field.
diff --git a/doc/documentation.rst b/doc/documentation.rst
@@ -31,20 +31,20 @@ Building Documentation
 To generate documentation using the ``@doc`` alias, all that's required to is
 to build this alias:
 
-::
+.. code:: console
 
   $ dune build @doc
 
 An index page containing links to all the opam packages in your project can be
 found in:
 
-::
+.. code:: console
 
   $ open _build/default/_doc/_html/index.html
 
 Documentation for private libraries may also be built with:
 
-::
+.. code:: console
 
   $ dune build @doc-private
 

diff --git a/doc/dune-files.rst b/doc/dune-files.rst
@@ -776,7 +776,7 @@ You can point Dune to an explicit ``dune-workspace`` file with the
 support, so developers can test that the code builds with all OCaml versions by
 simply running:
 
-.. code:: bash
+.. code:: console
 
     $ dune build --workspace dune-workspace.dev @all @runtest
 

diff --git a/doc/dune-libs.rst b/doc/dune-libs.rst
@@ -150,9 +150,9 @@ file, the version is obtained by querying the version control
 system. For instance, the following Git command is used in Git
 repositories:
 
-.. code:: bash
+.. code:: console
 
-          git describe --always --dirty --abbrev=7
+   $ git describe --always --dirty --abbrev=7
 
 which produces a human readable version string of the form
 ``<version>-<commits-since-version>-<hash>[-dirty]``.

diff --git a/doc/faq.rst b/doc/faq.rst
@@ -124,7 +124,7 @@ It is possible to use the ``ocaml-print-intf`` program (available on opam
 through ``$ opam install ocaml-print-intf``) to generate the right ``mli``
 file:
 
-.. code:: bash
+.. code:: console
 
   $ dune exec -- ocaml-print-intf ocaml_print_intf.ml
   val root_from_verbose_output : string list -> string
@@ -156,7 +156,7 @@ Suppose you have a library defined in ``src/foo/dune``:
 You can build this library on its own by running the following from the project
 root directory:
 
-.. code:: bash
+.. code:: console
 
    $ dune build %{cmxa:src/foo/my_library}
 

diff --git a/doc/hacking.rst b/doc/hacking.rst
@@ -17,9 +17,9 @@ Dependencies
 
 To create a directory-local opam switch with the dependencies necessary to build the tests, run:
 
-.. code:: sh
+.. code:: console
 
-   make dev-switch
+  $ make dev-switch
 
 Bootstrapping
 =============
@@ -44,16 +44,16 @@ bootstraps (if necessary) and runs ``./dune.exe build @install``.
 If you want to just run the bootstrapping step itself, build the ``bootstrap``
 phony target with
 
-.. code:: sh
+.. code:: console
 
-   make bootstrap
+   $ make bootstrap
 
 You can always rerun this to bootstrap again.
 
 Once you've bootstrapped Dune, you should be using it to develop Dune itself.
 Here are the most common commands you'll be running:
 
-.. code:: sh
+.. code:: console
 
    # to make sure everything compiles:
    $ ./dune.exe build @check
@@ -97,7 +97,7 @@ we use the ppx_expect_ framework, where we introduce tests via
 For integration tests, we use a system similar to `Cram tests
 <https://bitheap.org/cram/>`_ for testing shell commands and their behavior:
 
-.. code:: bash
+.. code:: console
 
    $ echo 'Hello, world!'
    Hello, world!
@@ -344,13 +344,13 @@ sphinx_rtd_theme_ and sphinx-copybutton_.
 
 Build the documentation with
 
-.. code:: sh
+.. code:: console
 
    $ make doc
 
 For automatically updated builds, you can install sphinx-autobuild_, and run
 
-.. code:: sh
+.. code:: console
 
    $ make livedoc
 
@@ -395,6 +395,11 @@ then it is possible to use the ``::`` shortcut to end a line with a single
 For links, prefer references that use ``:doc:`` (link to a whole document) or
 ``:term:`` (link to a definition in the glossary) to ``:ref:``.
 
+Use the right lexers:
+- ``dune`` for dune and related files
+- ``opam`` for opam files
+- ``console`` for shell sessions and commands (start with ``$``)
+
 Style
 -----
 
@@ -782,7 +787,7 @@ Build the Docker image from the root directory of this repo.
 
 E.g., run
 
-.. code:: sh
+.. code:: console
 
    $ docker build . -f bench/monorepo/bench.Dockerfile --tag=dune-monorepo-benchmark
 
@@ -791,7 +796,7 @@ as a volume. Generate this directory with a script from the
 `ocaml-monorepo-benchmark <https://github.com/ocaml-dune/ocaml-monorepo-benchmark>`_
 repository:
 
-.. code:: sh
+.. code:: console
 
    $ git clone https://github.com/ocaml-dune/ocaml-monorepo-benchmark.git
    $ cd ocaml-monorepo-benchmark
@@ -804,7 +809,7 @@ requirement of `current-bench <https://github.com/ocurrent/current-bench>`_).
 From within the container the benchmarks can be started by running `make bench`.
 Do all this in a single command with:
 
-.. code:: sh
+.. code:: console
 
    $ docker run -it --volume=/tmp/duniverse:/home/opam/bench-dir/current-bench-data/duniverse dune-monorepo-benchmark bash --login -c 'make bench'
 

diff --git a/doc/howto/bundle.rst b/doc/howto/bundle.rst
@@ -7,7 +7,7 @@ from other files in your project.
 Folder Structure
 ----------------
 
-.. code:: bash
+.. code:: console
 
     $ tree src
     src

diff --git a/doc/howto/formatting.rst b/doc/howto/formatting.rst
@@ -46,7 +46,7 @@ Running the Formatters
 Run the ``dune build @fmt`` command. It will format the source files in the
 corresponding project and display the differences:
 
-.. code::
+.. code:: console
 
     $ dune build @fmt
     --- hello.ml
@@ -60,7 +60,7 @@ corresponding project and display the differences:
 Then it's possible to accept the correction by calling ``dune promote`` to
 replace the source files with the corrected versions.
 
-.. code::
+.. code:: console
 
     $ dune promote
     Promoting _build/default/hello.ml.formatted to hello.ml.

diff --git a/doc/instrumentation.rst b/doc/instrumentation.rst
@@ -66,14 +66,14 @@ Activating an instrumentation backend can be done via the command line or the
 
 Via the command line, it is done as follows:
 
-.. code:: bash
+.. code:: console
 
    $ dune build --instrument-with <names>
 
 Here ``<names>`` is a comma-separated list of instrumentation backends. For
 example:
 
-.. code:: bash
+.. code:: console
 
    $ dune build --instrument-with bisect_ppx,landmarks
 

diff --git a/doc/jsoo.rst b/doc/jsoo.rst
@@ -7,7 +7,7 @@ JavaScript Compilation With Js_of_ocaml
 Js_of_ocaml_ is a compiler from OCaml to JavaScript. The compiler works by
 translating OCaml bytecode to JS files. The compiler can be installed with opam:
 
-.. code:: bash
+.. code:: console
 
    $ opam install js_of_ocaml-compiler
 
@@ -21,9 +21,9 @@ libraries/executables to JS.
 To build a JS executable, just define an executable as you would normally.
 Consider this example:
 
-.. code:: bash
+.. code:: console
 
-   echo 'print_endline "hello from js"' > foo.ml
+   $ echo 'print_endline "hello from js"' > foo.ml
 
 With the following ``dune`` file:
 
@@ -33,7 +33,7 @@ With the following ``dune`` file:
 
 And then request the ``.js`` target:
 
-.. code:: bash
+.. code:: console
 
    $ dune build ./foo.bc.js
    $ node _build/default/foo.bc.js

diff --git a/doc/melange.rst b/doc/melange.rst
@@ -11,7 +11,7 @@ Introduction
 JavaScript. It produces one JavaScript file per OCaml module. Melange can
 be installed with opam:
 
-.. code:: bash
+.. code:: console
 
    $ opam install melange
 
@@ -53,9 +53,9 @@ Next, write a :ref:`dune<dune-files>` file with a :ref:`melange-emit` stanza:
 
 Finally, add a source file to build:
 
-.. code:: bash
+.. code:: console
 
-  echo 'Js.log "hello from melange"' > hello.ml
+  $ echo 'Js.log "hello from melange"' > hello.ml
 
 After running ``dune build @melange`` or just ``dune build``, Dune
 produces the following file structure:
@@ -73,7 +73,7 @@ produces the following file structure:
 
 The resulting JavaScript can now be run:
 
-.. code:: bash
+.. code:: console
 
    $ node _build/default/output/hello.js
    hello from melange
@@ -115,7 +115,7 @@ be placed. In particular, the folder will be placed under
 The result of building a  ``melange.emit`` stanza will match the file structure
 of the source tree. For example, given the following source tree:
 
-.. code:: bash
+.. code::
 
     ├── dune # (melange.emit (target output) (libraries lib))
     ├── app.ml