From d6be994ef8ed6e81dc069a5cc3c8604619cc9d56 Mon Sep 17 00:00:00 2001 From: Erik Faye-Lund Date: Tue, 4 Jun 2019 14:14:13 +0200 Subject: [PATCH] docs: use code-blocks Sphinx can syntax-highlight a block if we use the right syntax. Reviewed-by: Eric Engestrom Part-of: --- docs/application-issues.rst | 2 +- docs/codingstyle.rst | 14 +++++++------- docs/devinfo.rst | 2 +- docs/download.rst | 4 ++-- docs/egl.rst | 2 +- docs/llvmpipe.rst | 10 +++++----- docs/meson.rst | 36 ++++++++++++++++++------------------ docs/submittingpatches.rst | 8 ++++---- 8 files changed, 39 insertions(+), 39 deletions(-) diff --git a/docs/application-issues.rst b/docs/application-issues.rst index 22e3ec8be43..e3e511b18e1 100644 --- a/docs/application-issues.rst +++ b/docs/application-issues.rst @@ -35,7 +35,7 @@ than the given year. For example, if the game was released in 2001, do -:: +.. code-block:: console export MESA_EXTENSION_MAX_YEAR=2001 diff --git a/docs/codingstyle.rst b/docs/codingstyle.rst index eda7f9d51ba..198289aadec 100644 --- a/docs/codingstyle.rst +++ b/docs/codingstyle.rst @@ -17,7 +17,7 @@ Basic formatting guidelines - Opening braces go on the same line as the if/for/while statement. For example: - :: + .. code-block:: c if (condition) { foo; @@ -30,7 +30,7 @@ Basic formatting guidelines - This GNU indent command generally does the right thing for formatting: - :: + .. code-block:: console indent -br -i3 -npcs --no-tabs infile.c -o outfile.c @@ -41,20 +41,20 @@ Basic formatting guidelines Single-line comments: - :: + .. code-block:: c /* null-out pointer to prevent dangling reference below */ bufferObj = NULL; Or, - :: + .. code-block:: c bufferObj = NULL; /* prevent dangling reference below */ Multi-line comment: - :: + .. code-block:: c /* If this is a new buffer object id, or one which was generated but * never used before, allocate a buffer object now. @@ -62,7 +62,7 @@ Basic formatting guidelines We try to quote the OpenGL specification where prudent: - :: + .. code-block:: c /* Page 38 of the PDF of the OpenGL ES 3.0 spec says: * @@ -78,7 +78,7 @@ Basic formatting guidelines Function comment example: - :: + .. code-block:: c /** * Create and initialize a new buffer object. Called via the diff --git a/docs/devinfo.rst b/docs/devinfo.rst index 4e06bbf7e79..f9333810e9d 100644 --- a/docs/devinfo.rst +++ b/docs/devinfo.rst @@ -13,7 +13,7 @@ To add a new GL extension to Mesa you have to do at least the following. - If ``glext.h`` doesn't define the extension, edit ``include/GL/gl.h`` and add code like this: - :: + .. code-block:: c #ifndef GL_EXT_the_extension_name #define GL_EXT_the_extension_name 1 diff --git a/docs/download.rst b/docs/download.rst index eb4058ce089..56a7783aea5 100644 --- a/docs/download.rst +++ b/docs/download.rst @@ -25,13 +25,13 @@ Mesa releases are available in two formats: ``.tar.xz`` and ``.tar.gz``. To unpack the tarball: -:: +.. code-block:: console tar xf mesa-Y.N.P.tar.xz or -:: +.. code-block:: console tar xf mesa-Y.N.P.tar.gz diff --git a/docs/egl.rst b/docs/egl.rst index 9b7f2c035a2..8ca6c780ded 100644 --- a/docs/egl.rst +++ b/docs/egl.rst @@ -18,7 +18,7 @@ Build EGL #. Configure your build with the desired client APIs and enable the driver for your hardware. For example: - :: + .. code-block:: console $ meson configure \ -D egl=true \ diff --git a/docs/llvmpipe.rst b/docs/llvmpipe.rst index 826bf05816e..ec8e92dc0a8 100644 --- a/docs/llvmpipe.rst +++ b/docs/llvmpipe.rst @@ -32,7 +32,7 @@ Requirements For Linux, on a recent Debian based distribution do: - :: + .. code-block:: console aptitude install llvm-dev @@ -43,7 +43,7 @@ Requirements For a RPM-based distribution do: - :: + .. code-block:: console yum install llvm-devel @@ -75,13 +75,13 @@ Building To build everything on Linux invoke scons as: -:: +.. code-block:: console scons build=debug libgl-xlib Alternatively, you can build it with meson with: -:: +.. code-block:: console mkdir build cd build @@ -91,7 +91,7 @@ Alternatively, you can build it with meson with: but the rest of these instructions assume that scons is used. For Windows the procedure is similar except the target: -:: +.. code-block:: console scons platform=windows build=debug libgl-gdi diff --git a/docs/meson.rst b/docs/meson.rst index 0b60b881902..2f9187dcaf8 100644 --- a/docs/meson.rst +++ b/docs/meson.rst @@ -28,13 +28,13 @@ Unix-like OSes If Meson is not already installed on your system, you can typically install it with your package installer. For example: -:: +.. code-block:: console sudo apt-get install meson # Ubuntu or -:: +.. code-block:: console sudo dnf install meson # Fedora @@ -54,20 +54,20 @@ modules (mako). You also need pkg-config (a hard dependency of meson), flex, and bison. The easiest way to install everything you need is with `chocolatey `__. -:: +.. code-block:: console choco install python3 winflexbison pkgconfiglite You can even use chocolatey to install mingw and ninja (ninja can be used with MSVC as well) -:: +.. code-block:: console choco install ninja mingw Then install meson using pip -:: +.. code-block:: console py -3 -m pip install meson mako @@ -92,7 +92,7 @@ for each configuration you might want to use. Basic configuration is done with: -:: +.. code-block:: console meson build/ @@ -102,7 +102,7 @@ configuration option (see below). To review the options which Meson chose, run: -:: +.. code-block:: console meson configure build/ @@ -118,7 +118,7 @@ With additional arguments ``meson configure`` can be used to change options for a previously configured build directory. All options passed to this command are in the form ``-D "option"="value"``. For example: -:: +.. code-block:: console meson configure build/ -Dprefix=/tmp/install -Dglx=true @@ -131,7 +131,7 @@ an empty list (``-D platforms=[]``). Once you've run the initial ``meson`` command successfully you can use your configured backend to build the project in your build directory: -:: +.. code-block:: console ninja -C build/ @@ -139,7 +139,7 @@ The next step is to install the Mesa libraries, drivers, etc. This also finishes up some final steps of the build process (such as creating symbolic links for drivers). To install: -:: +.. code-block:: console ninja -C build/ install @@ -149,7 +149,7 @@ symbolic links for drivers). To install: configuration tool) as part of the build process, Meson does not do this. Instead, you will need do this: - :: + .. code-block:: console ninja -C build/ xmlpool-pot xmlpool-update-po xmlpool-gmo @@ -188,7 +188,7 @@ Developers will often want to install Mesa to a testing directory rather than the system library directory. This can be done with the --prefix option. For example: -:: +.. code-block:: console meson --prefix="${PWD}/build/install" build/ @@ -211,7 +211,7 @@ they are guaranteed to persist across rebuilds and reconfigurations. This example sets -fmax-errors for compiling C sources and -DMAGIC=123 for C++ sources: -:: +.. code-block:: console meson builddir/ -Dc_args=-fmax-errors=10 -Dcpp_args=-DMAGIC=123 @@ -226,7 +226,7 @@ build dir for a different compiler. This is an example of specifying the clang compilers and cleaning the build directory before reconfiguring with an extra C option: -:: +.. code-block:: console CC=clang CXX=clang++ meson build-clang ninja -C build-clang @@ -251,7 +251,7 @@ libraries, it will never find libllvm.so. There is also a ``-Dcmake_module_path`` option in this meson version, which points to the root of an alternative installation (the prefix). For example: -:: +.. code-block:: console meson builddir -Dcmake_module_path=/home/user/mycmake/prefix @@ -270,7 +270,7 @@ custom-llvm.ini Then configure meson: -:: +.. code-block:: console meson builddir/ --native-file custom-llvm.ini @@ -279,7 +279,7 @@ Meson < 0.49 doesn't support native files, so to specify a custom windows), which will be searched for ``llvm-config``, ``llvm-config$version``, and ``llvm-config-$version``: -:: +.. code-block:: console PATH=/path/to/folder/with/llvm-config:$PATH meson build @@ -300,7 +300,7 @@ Obviously, only cmake or llvm-config is required. Then configure meson: -:: +.. code-block:: console meson builddir/ --cross-file cross-llvm.ini diff --git a/docs/submittingpatches.rst b/docs/submittingpatches.rst index c99e8d0b012..55b97cd4279 100644 --- a/docs/submittingpatches.rst +++ b/docs/submittingpatches.rst @@ -383,7 +383,7 @@ Git tips - ``git rebase -i ...`` is your friend. Don't be afraid to use it. - Apply a fixup to commit FOO. - :: + .. code-block:: console git add ... git commit --fixup=FOO @@ -391,20 +391,20 @@ Git tips - Test for build breakage between patches e.g last 8 commits. - :: + .. code-block:: console git rebase -i --exec="ninja -C build/" HEAD~8 - Sets the default mailing address for your repo. - :: + .. code-block:: console git config --local sendemail.to mesa-dev@lists.freedesktop.org - Add version to subject line of patch series in this case for the last 8 commits before sending. - :: + .. code-block:: console git send-email --subject-prefix="PATCH v4" HEAD~8 git send-email -v4 @~8 # shorter version, inherited from git format-patch