[Mesa-dev] [PATCH 12/16] docs: Fix Sphinx compile errors.
Eric Engestrom
eric.engestrom at intel.com
Fri May 25 14:53:15 UTC 2018
On Thursday, 2018-05-24 17:27:15 -0700, Laura Ekstrand wrote:
> This just involves some quick fixes to formatting of the affected pages.
> ---
> docs/autoconf.rst | 1 +
> docs/conf.py | 2 +-
> docs/dispatch.rst | 72 ++++++++++++++++++++++--------------------------
> docs/egl.rst | 2 ++
> docs/releasing.rst | 14 +++++-----
> docs/relnotes.rst | 72 +++++++++++++++++++++++++++---------------------
> docs/relnotes/17.0.5.rst | 2 +-
> docs/relnotes/9.2.2.rst | 1 -
> 8 files changed, 86 insertions(+), 80 deletions(-)
>
> diff --git a/docs/autoconf.rst b/docs/autoconf.rst
> index 007252feb0..25ba71cf66 100644
> --- a/docs/autoconf.rst
> +++ b/docs/autoconf.rst
> @@ -102,6 +102,7 @@ There are also a few general options for altering the Mesa build:
> This option ensures that assembly will not be used.
>
> ``--build=``
> + .. See host
> ``--host=``
> By default, the build will compile code for the architecture that
> it's running on. In order to build cross-compile Mesa on a x86-64
> diff --git a/docs/conf.py b/docs/conf.py
> index dcdbdd51db..33bf717a87 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -99,7 +99,7 @@ html_theme = 'sphinx_rtd_theme'
> # Add any paths that contain custom static files (such as style sheets) here,
> # relative to this directory. They are copied after the builtin static files,
> # so a file named "default.css" will overwrite the builtin "default.css".
> -html_static_path = ['_static']
> +html_static_path = []
>
>
> # -- Options for HTMLHelp output ------------------------------------------
> diff --git a/docs/dispatch.rst b/docs/dispatch.rst
> index d6f8542c68..aba7192c31 100644
> --- a/docs/dispatch.rst
> +++ b/docs/dispatch.rst
> @@ -62,18 +62,17 @@ conceptually simple:
> This can be implemented in just a few lines of C code. The file
> ``src/mesa/glapi/glapitemp.h`` contains code very similar to this.
>
> - +--------------------------------------------------------------------------+
> - | :: |
> - | |
> - | void glVertex3f(GLfloat x, GLfloat y, GLfloat z) |
> - | { |
> - | const struct _glapi_table * const dispatch = GET_DISPATCH(); |
> - | |
> - | (*dispatch->Vertex3f)(x, y, z); |
> - | } |
> - +--------------------------------------------------------------------------+
> - | Sample dispatch function |
> - +--------------------------------------------------------------------------+
> +Sample dispatch function
> +~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +.. code-block:: c
> +
> + void glVertex3f(GLfloat x, GLfloat y, GLfloat z)
> + {
> + const struct _glapi_table * const dispatch = GET_DISPATCH();
> +
> + (*dispatch->Vertex3f)(x, y, z);
> + }
>
> The problem with this simple implementation is the large amount of
> overhead that it adds to every GL function call.
> @@ -118,16 +117,14 @@ resulting implementation of ``GET_DISPATCH`` is slightly more complex,
> but it avoids the expensive ``pthread_getspecific`` call in the common
> case.
>
> - +--------------------------------------------------------------------------+
> - | :: |
> - | |
> - | #define GET_DISPATCH() \ |
> - | (_glapi_Dispatch != NULL) \ |
> - | ? _glapi_Dispatch : pthread_getspecific(&_glapi_Dispatch_key |
> - | ) |
> - +--------------------------------------------------------------------------+
> - | Improved ``GET_DISPATCH`` Implementation |
> - +--------------------------------------------------------------------------+
> +Improved ``GET_DISPATCH`` Implementation
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +.. code-block:: c
> +
> + #define GET_DISPATCH() \
> + (_glapi_Dispatch != NULL) \
> + ? _glapi_Dispatch : pthread_getspecific(&_glapi_Dispatch_key)
> +
>
> 3.2. ELF TLS
> ~~~~~~~~~~~~
> @@ -145,16 +142,14 @@ with direct rendering drivers that use either interface. Once the
> pointer is properly declared, ``GET_DISPACH`` becomes a simple variable
> reference.
>
> - +--------------------------------------------------------------------------+
> - | :: |
> - | |
> - | extern __thread struct _glapi_table *_glapi_tls_Dispatch |
> - | __attribute__((tls_model("initial-exec"))); |
> - | |
> - | #define GET_DISPATCH() _glapi_tls_Dispatch |
> - +--------------------------------------------------------------------------+
> - | TLS ``GET_DISPATCH`` Implementation |
> - +--------------------------------------------------------------------------+
> +TLS ``GET_DISPATCH`` Implementation
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +.. code-block:: c
> +
> + extern __thread struct _glapi_table *_glapi_tls_Dispatch
> + __attribute__((tls_model("initial-exec")));
> +
> + #define GET_DISPATCH() _glapi_tls_Dispatch
>
> Use of this path is controlled by the preprocessor define
> ``GLX_USE_TLS``. Any platform capable of using TLS should use this as
> @@ -203,13 +198,12 @@ the assembly source file different implementations of the macro are
> selected based on the defined preprocessor variables. The assembly code
> then consists of a series of invocations of the macros such as:
>
> - +--------------------------------------------------------------------------+
> - | :: |
> - | |
> - | GL_STUB(Color3fv, _gloffset_Color3fv) |
> - +--------------------------------------------------------------------------+
> - | SPARC Assembly Implementation of ``glColor3fv`` |
> - +--------------------------------------------------------------------------+
> +SPARC Assembly Implementation of ``glColor3fv``
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +.. code-block:: c
> +
> + GL_STUB(Color3fv, _gloffset_Color3fv)
>
> The benefit of this technique is that changes to the calling pattern
> (i.e., addition of a new dispatch table pointer access method) require
> diff --git a/docs/egl.rst b/docs/egl.rst
> index bdd9290280..58caf945e9 100644
> --- a/docs/egl.rst
> +++ b/docs/egl.rst
> @@ -64,6 +64,8 @@ time
> right platforms automatically.
>
> ``--enable-gles1``
> + .. See --enable-gles2
> +
> ``--enable-gles2``
> These options enable OpenGL ES support in OpenGL. The result is one
> big internal library that supports multiple APIs.
> diff --git a/docs/releasing.rst b/docs/releasing.rst
> index ad7dcb9c38..dff272bd30 100644
> --- a/docs/releasing.rst
> +++ b/docs/releasing.rst
> @@ -342,13 +342,13 @@ Making a new release
> These are the instructions for making a new Mesa release.
>
> Get latest source files
> -~~~~~~~~~~~~~~~~~~~~~~~
> +-----------------------
>
> Ensure the latest code is available - both in your local master and the
> relevant branch.
>
> Perform basic testing
> -~~~~~~~~~~~~~~~~~~~~~
> +---------------------
>
> Most of the testing should already be done during the
> `cherry-pick <#pickntest>`__ and `pre-announce <#prerelease>`__ stages.
> @@ -444,13 +444,13 @@ Here is one solution that I've been using.
> unset VK_ICD_FILENAMES
>
> Update version in file VERSION
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +------------------------------
>
> Increment the version contained in the file VERSION at Mesa's top-level,
> then commit this change.
>
> Create release notes for the new release
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +----------------------------------------
>
> Create a new file docs/relnotes/X.Y.Z.html, (follow the style of the
> previous release notes). Note that the sha256sums section of the release
> @@ -476,7 +476,7 @@ Commit these changes and push the branch.
> git push origin HEAD
>
> Use the release.sh script from xorg `util-modular <https://cgit.freedesktop.org/xorg/util/modular/>`__
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +------------------------------------------------------------------------------------------------------
>
> Start the release process.
>
> @@ -491,13 +491,13 @@ your GPG and SSH passphrase(s) to sign and upload the files,
> respectively.
>
> Add the sha256sums to the release notes
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +---------------------------------------
>
> Edit docs/relnotes/X.Y.Z.html to add the sha256sums as available in the
> mesa-X.Y.Z.announce template. Commit this change.
>
> Back on mesa master, add the new release notes into the tree
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +------------------------------------------------------------
>
> Something like the following steps will do the trick:
>
> diff --git a/docs/relnotes.rst b/docs/relnotes.rst
> index aecec6ae3d..e418323f83 100644
> --- a/docs/relnotes.rst
> +++ b/docs/relnotes.rst
> @@ -234,7 +234,48 @@ file <versions.html>`__ and the following release notes.
>
> .. toctree::
> :maxdepth: 1
> + :hidden:
>
> + release-calendar
> + relnotes/18.1.0
> + relnotes/18.0.4
> + relnotes/18.0.3
> + relnotes/18.0.2
> + relnotes/18.0.1
> + relnotes/18.0.0
> + relnotes/17.3.9
> + relnotes/17.3.8
> + relnotes/17.3.7
> + relnotes/17.3.6
> + relnotes/17.3.5
> + relnotes/17.3.4
> + relnotes/17.3.3
> + relnotes/17.3.2
> + relnotes/17.3.1
> + relnotes/17.3.0
> + relnotes/17.2.8
> + relnotes/17.2.7
> + relnotes/17.2.6
> + relnotes/17.2.5
> + relnotes/17.2.4
> + relnotes/17.2.3
> + relnotes/17.2.2
> + relnotes/17.2.1
> + relnotes/17.2.0
> + relnotes/17.1.10
> + relnotes/17.1.9
> + relnotes/17.1.8
> + relnotes/17.1.7
> + relnotes/17.1.6
> + relnotes/17.1.5
> + relnotes/17.1.4
> + relnotes/17.1.3
> + relnotes/17.1.2
> + relnotes/17.1.1
> + relnotes/17.1.0
> + relnotes/17.0.7
> + relnotes/17.0.6
> + relnotes/17.0.5
> relnotes/17.0.4
> relnotes/17.0.3
> relnotes/17.0.2
> @@ -396,35 +437,4 @@ file <versions.html>`__ and the following release notes.
> relnotes/6.4.2
> relnotes/6.4.1
> relnotes/6.4
> -
> -Versions of Mesa prior to 6.4 are summarized in the versions file and the following release notes.
> -
> -.. toctree::
> - :maxdepth: 1
> -
> versions
> - relnotes/6.3.2
> - relnotes/6.3.1
> - relnotes/6.3
> - relnotes/6.2.1
> - relnotes/6.2
> - relnotes/6.1
> - relnotes/6.0.1
> - relnotes/6.0
> - relnotes/5.1
> - relnotes/5.0.2
> - relnotes/5.0.1
> - relnotes/5.0
> - relnotes/4.1
> - relnotes/4.0.3
> - relnotes/4.0.2
> - relnotes/4.0.1
> - relnotes/4.0
> - relnotes/3.5
> - relnotes/3.4.2
> - relnotes/3.4.1
> - relnotes/3.4
> - relnotes/3.3
> - relnotes/3.2.1
> - relnotes/3.2
> - relnotes/3.1
> diff --git a/docs/relnotes/17.0.5.rst b/docs/relnotes/17.0.5.rst
> index fc42af13ce..cc8202d882 100644
> --- a/docs/relnotes/17.0.5.rst
> +++ b/docs/relnotes/17.0.5.rst
> @@ -64,7 +64,7 @@ Emil Velikov (5):
>
> - docs: add sha256 checksums for 17.0.4
> - winsys/sw/dri: don't use GNU void pointer arithmetic
> -- st/clover: add space between < and ::
> +- st/clover: add space between < and :\:
nit, but just enclose these two in `` ?
Although I guess backticks could be added to something in most lines of
each page of the relnotes really, but for now let's just have it build,
we can always add those everywhere later :)
> - configure.ac: check require\_basic\_egl only if egl enabled
> - st/mesa: automake: honour the vdpau header install location
>
> diff --git a/docs/relnotes/9.2.2.rst b/docs/relnotes/9.2.2.rst
> index 79216b7e61..49a181d9fc 100644
> --- a/docs/relnotes/9.2.2.rst
> +++ b/docs/relnotes/9.2.2.rst
> @@ -14,7 +14,6 @@ because GL\_ARB\_compatibility is not supported.
> MD5 checksums
> -------------
>
> -::
>
> New features
> ------------
> --
> 2.14.3
>
> _______________________________________________
> mesa-dev mailing list
> mesa-dev at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/mesa-dev
More information about the mesa-dev
mailing list