[1/7] jit,docs: use enum directive for enumeral types

Message ID 19033b481059d9e603d837a5671da541a9cc742f.1658754788.git.mliska@suse.cz
State New, archived
Headers
Series jit,docs: remove warnings and modernize the docs |

Commit Message

Martin Liška July 25, 2022, 8:52 a.m. UTC
  gcc/jit/ChangeLog:

	* docs/conf.py: Add needs_sphinx = '3.0' where c:type was added.
	* docs/index.rst: Remove note about it.
	* docs/topics/compilation.rst: Use enum directive and reference.
	* docs/topics/contexts.rst: Likewise.
	* docs/topics/expressions.rst: Likewise.
	* docs/topics/functions.rst: Likewise.
---
 gcc/jit/docs/conf.py                |  3 +++
 gcc/jit/docs/index.rst              |  7 -------
 gcc/jit/docs/topics/compilation.rst |  4 ++--
 gcc/jit/docs/topics/contexts.rst    |  6 +++---
 gcc/jit/docs/topics/expressions.rst | 10 +++++-----
 gcc/jit/docs/topics/functions.rst   |  2 +-
 6 files changed, 14 insertions(+), 18 deletions(-)
  

Comments

David Malcolm July 25, 2022, 10:35 p.m. UTC | #1
On Mon, 2022-07-25 at 10:52 +0200, Martin Liska wrote:
> gcc/jit/ChangeLog:
> 
>         * docs/conf.py: Add needs_sphinx = '3.0' where c:type was
> added.

Looking at the footer of https://gcc.gnu.org/onlinedocs/jit/index.html
I see we currently only have sphinx 1.7.6 installed.

Have you been talking with the gcc.gnu.org admins about bumping this
requirement?

Otherwise the patch looks OK

Dave
  
Martin Liška July 26, 2022, 4:47 a.m. UTC | #2
On 7/26/22 00:35, David Malcolm wrote:
> On Mon, 2022-07-25 at 10:52 +0200, Martin Liska wrote:
>> gcc/jit/ChangeLog:
>>
>>         * docs/conf.py: Add needs_sphinx = '3.0' where c:type was
>> added.
> 
> Looking at the footer of https://gcc.gnu.org/onlinedocs/jit/index.html
> I see we currently only have sphinx 1.7.6 installed.

Yep.

> 
> Have you been talking with the gcc.gnu.org admins about bumping this
> requirement?

Yes, working on that right now:

https://gcc.gnu.org/pipermail/gcc-patches/2022-July/598771.html

Thanks,
Martin

> 
> Otherwise the patch looks OK
> 
> Dave
>
  

Patch

diff --git a/gcc/jit/docs/conf.py b/gcc/jit/docs/conf.py
index 00f0e9887dd..062232ae280 100644
--- a/gcc/jit/docs/conf.py
+++ b/gcc/jit/docs/conf.py
@@ -39,6 +39,9 @@  source_suffix = '.rst'
 # The master toctree document.
 master_doc = 'index'
 
+# c:type directive is supported since 3.0
+needs_sphinx = '3.0'
+
 # General information about the project.
 project = u'libgccjit'
 copyright = u'2014-2022 Free Software Foundation, Inc.'
diff --git a/gcc/jit/docs/index.rst b/gcc/jit/docs/index.rst
index 3aff17d7a60..21c3140e238 100644
--- a/gcc/jit/docs/index.rst
+++ b/gcc/jit/docs/index.rst
@@ -45,10 +45,3 @@  Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-
-.. Some notes:
-
-   The Sphinx C domain appears to lack explicit support for enum values,
-   so I've been using :c:macro: for them.
-
-   See https://sphinx-doc.org/domains.html#the-c-domain
diff --git a/gcc/jit/docs/topics/compilation.rst b/gcc/jit/docs/topics/compilation.rst
index 9b1eed2dede..c5fa6eb0faf 100644
--- a/gcc/jit/docs/topics/compilation.rst
+++ b/gcc/jit/docs/topics/compilation.rst
@@ -158,14 +158,14 @@  For linking in object files, use :c:func:`gcc_jit_context_add_driver_option`.
 
 :c:func:`gcc_jit_context_compile_to_file` ignores the suffix of
 ``output_path``, and insteads uses the given
-:c:type:`enum gcc_jit_output_kind` to decide what to do.
+:c:enum:`gcc_jit_output_kind` to decide what to do.
 
 .. note::
 
    This is different from the ``gcc`` program, which does make use of the
    suffix of the output file when determining what to do.
 
-.. type:: enum gcc_jit_output_kind
+.. enum:: gcc_jit_output_kind
 
 The available kinds of output are:
 
diff --git a/gcc/jit/docs/topics/contexts.rst b/gcc/jit/docs/topics/contexts.rst
index dfbe968e127..205b5f3dcf5 100644
--- a/gcc/jit/docs/topics/contexts.rst
+++ b/gcc/jit/docs/topics/contexts.rst
@@ -311,7 +311,7 @@  String Options
 
    Set a string option of the context.
 
-   .. type:: enum gcc_jit_str_option
+   .. enum:: gcc_jit_str_option
 
    The parameter ``value`` can be NULL.   If non-NULL, the call takes a
    copy of the underlying string, so it is valid to pass in a pointer to
@@ -334,7 +334,7 @@  Boolean options
   Set a boolean option of the context.
   Zero is "false" (the default), non-zero is "true".
 
-  .. type:: enum gcc_jit_bool_option
+  .. enum:: gcc_jit_bool_option
 
   .. macro:: GCC_JIT_BOOL_OPTION_DEBUGINFO
 
@@ -513,7 +513,7 @@  Integer options
 
   Set an integer option of the context.
 
-  .. type:: enum gcc_jit_int_option
+  .. enum:: gcc_jit_int_option
 
   There is just one integer option specified this way:
 
diff --git a/gcc/jit/docs/topics/expressions.rst b/gcc/jit/docs/topics/expressions.rst
index 91ee8a9c74a..49b7e14ae2b 100644
--- a/gcc/jit/docs/topics/expressions.rst
+++ b/gcc/jit/docs/topics/expressions.rst
@@ -309,7 +309,7 @@  Unary Operations
 
    The parameter ``result_type`` must be a numeric type.
 
-.. type:: enum gcc_jit_unary_op
+.. enum:: gcc_jit_unary_op
 
 The available unary operations are:
 
@@ -376,7 +376,7 @@  Binary Operations
 
    The parameter ``result_type`` must be a numeric type.
 
-.. type:: enum gcc_jit_binary_op
+.. enum:: gcc_jit_binary_op
 
 The available binary operations are:
 
@@ -534,7 +534,7 @@  Comparisons
 
    Build a boolean rvalue out of the comparison of two other rvalues.
 
-.. type:: enum gcc_jit_comparison
+.. enum:: gcc_jit_comparison
 
 =======================================  ============
 Comparison                               C equivalent
@@ -711,7 +711,7 @@  where the rvalue is computed by reading from the storage area.
 
    The "model" parameter determines the thread-local storage model of the "lvalue":
 
-   .. type:: enum gcc_jit_tls_model
+   .. enum:: gcc_jit_tls_model
 
    .. c:macro:: GCC_JIT_TLS_MODEL_NONE
 
@@ -841,7 +841,7 @@  Global variables
    The "kind" parameter determines the visibility of the "global" outside
    of the :c:type:`gcc_jit_result`:
 
-   .. type:: enum gcc_jit_global_kind
+   .. enum:: gcc_jit_global_kind
 
    .. c:macro:: GCC_JIT_GLOBAL_EXPORTED
 
diff --git a/gcc/jit/docs/topics/functions.rst b/gcc/jit/docs/topics/functions.rst
index 0845fe0f7d3..d6d4fe90834 100644
--- a/gcc/jit/docs/topics/functions.rst
+++ b/gcc/jit/docs/topics/functions.rst
@@ -80,7 +80,7 @@  Functions
 
    Create a gcc_jit_function with the given name and parameters.
 
-   .. type:: enum gcc_jit_function_kind
+   .. enum:: gcc_jit_function_kind
 
    This enum controls the kind of function created, and has the following
    values: