[libvirt PATCH 0/2] docs: Use list-tables in reStructuredText
It's easier to modify than the ASCII-art alternative. Andrea Bolognani (2): docs: Convert existing tables to list-table docs: Document list-tables as recommended docs/coding-style.rst | 53 +++++++++++------- docs/glib-adoption.rst | 123 +++++++++++++++++++++++++++-------------- docs/styleguide.rst | 20 +++++++ 3 files changed, 134 insertions(+), 62 deletions(-) -- 2.25.4
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/coding-style.rst | 53 +++++++++++------- docs/glib-adoption.rst | 123 +++++++++++++++++++++++++++-------------- 2 files changed, 114 insertions(+), 62 deletions(-) diff --git a/docs/coding-style.rst b/docs/coding-style.rst index 151ea87b6a..15c3a0b22d 100644 --- a/docs/coding-style.rst +++ b/docs/coding-style.rst @@ -547,27 +547,38 @@ Attribute annotations Use the following annotations to help the compiler and/or static analysis tools understand the code better: -+-------------------------------+------------------------------------------------------------+ -| Macro | Meaning | -+===============================+============================================================+ -| ``ATTRIBUTE_NONNULL`` | passing NULL for this parameter is not allowed | -+-------------------------------+------------------------------------------------------------+ -| ``ATTRIBUTE_PACKED`` | force a structure to be packed | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_FALLTHROUGH`` | allow code reuse by multiple switch cases | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_NO_INLINE`` | the function is mocked in the test suite | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_NORETURN`` | the function never returns | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_NULL_TERMINATED`` | last parameter must be NULL | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_PRINTF`` | validate that the formatting string matches parameters | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_UNUSED`` | parameter is unused in this implementation of the function | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_WARN_UNUSED_RESULT`` | the return value must be checked | -+-------------------------------+------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + + * - Macro + - Meaning + + * - ``ATTRIBUTE_NONNULL`` + - passing NULL for this parameter is not allowed + + * - ``ATTRIBUTE_PACKED`` + - force a structure to be packed + + * - ``G_GNUC_FALLTHROUGH`` + - allow code reuse by multiple switch cases + + * - ``G_GNUC_NO_INLINE`` + - the function is mocked in the test suite + + * - ``G_GNUC_NORETURN`` + - the function never returns + + * - ``G_GNUC_NULL_TERMINATED`` + - last parameter must be NULL + + * - ``G_GNUC_PRINTF`` + - validate that the formatting string matches parameters + + * - ``G_GNUC_UNUSED`` + - parameter is unused in this implementation of the function + + * - ``G_GNUC_WARN_UNUSED_RESULT`` + - the return value must be checked File handling ------------- diff --git a/docs/glib-adoption.rst b/docs/glib-adoption.rst index 62ddd7c61d..a5dca47f5e 100644 --- a/docs/glib-adoption.rst +++ b/docs/glib-adoption.rst @@ -53,44 +53,85 @@ The following libvirt APIs have been deleted already: ``VIR_STRDUP``, ``VIR_STRNDUP`` Prefer the GLib APIs ``g_strdup`` and ``g_strndup``. -+-------------------------------+--------------------------------------+-------------------------------------------+ -| deleted version | GLib version | Notes | -+===============================+======================================+===========================================+ -| ``VIR_AUTOPTR`` | ``g_autoptr`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_AUTOCLEAN`` | ``g_auto`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_AUTOFREE`` | ``g_autofree`` | The GLib version does not use parentheses | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_AUTOUNREF`` | ``g_autoptr`` | The cleanup function needs to be defined | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_DEFINE_AUTOPTR_FUNC`` | ``G_DEFINE_AUTOPTR_CLEANUP_FUNC`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_DEFINE_AUTOCLEAN_FUNC`` | ``G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_STEAL_PTR`` | ``g_steal_pointer`` | ``a = f(&b)`` instead of ``f(a, b)`` | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_RETURN_PTR`` | ``return g_steal_pointer`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``ARRAY_CARDINALITY`` | ``G_N_ELEMENTS`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``ATTRIBUTE_FALLTHROUGH`` | ``G_GNUC_FALLTHROUGH`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``ATTRIBUTE_FMT_PRINTF`` | ``G_GNUC_PRINTF`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``ATTRIBUTE_NOINLINE`` | ``G_GNUC_NO_INLINE`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``ATTRIBUTE_NORETURN`` | ``G_GNUC_NORETURN`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``ATTRIBUTE_RETURN_CHECK`` | ``G_GNUC_WARN_UNUSED_RESULT`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``ATTRIBUTE_SENTINEL`` | ``G_GNUC_NULL_TERMINATED`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``ATTRIBUTE_UNUSED`` | ``G_GNUC_UNUSED`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_STRDUP`` | ``g_strdup`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_STRNDUP`` | ``g_strndup`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``virStrerror`` | ``g_strerror`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ +.. list-table:: + :header-rows: 1 + + * - deleted version + - GLib version + - Notes + + * - ``VIR_AUTOPTR`` + - ``g_autoptr`` + - + + * - ``VIR_AUTOCLEAN`` + - ``g_auto`` + - + + * - ``VIR_AUTOFREE`` + - ``g_autofree`` + - The GLib version does not use parentheses + + * - ``VIR_AUTOUNREF`` + - ``g_autoptr`` + - The cleanup function needs to be defined + + * - ``VIR_DEFINE_AUTOPTR_FUNC`` + - ``G_DEFINE_AUTOPTR_CLEANUP_FUNC`` + - + + * - ``VIR_DEFINE_AUTOCLEAN_FUNC`` + - ``G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC`` + - + + * - ``VIR_STEAL_PTR`` + - ``g_steal_pointer`` + - ``a = f(&b)`` instead of ``f(a, b)`` + + * - ``VIR_RETURN_PTR`` + - ``return g_steal_pointer`` + - + + * - ``ARRAY_CARDINALITY`` + - ``G_N_ELEMENTS`` + - + + * - ``ATTRIBUTE_FALLTHROUGH`` + - ``G_GNUC_FALLTHROUGH`` + - + + * - ``ATTRIBUTE_FMT_PRINTF`` + - ``G_GNUC_PRINTF`` + - + + * - ``ATTRIBUTE_NOINLINE`` + - ``G_GNUC_NO_INLINE`` + - + + * - ``ATTRIBUTE_NORETURN`` + - ``G_GNUC_NORETURN`` + - + + * - ``ATTRIBUTE_RETURN_CHECK`` + - ``G_GNUC_WARN_UNUSED_RESULT`` + - + + * - ``ATTRIBUTE_SENTINEL`` + - ``G_GNUC_NULL_TERMINATED`` + - + + * - ``ATTRIBUTE_UNUSED`` + - ``G_GNUC_UNUSED`` + - + + * - ``VIR_STRDUP`` + - ``g_strdup`` + - + + * - ``VIR_STRNDUP`` + - ``g_strndup`` + - + + * - ``virStrerror`` + - ``g_strerror`` + - -- 2.25.4
On Thu, May 07, 2020 at 14:46:38 +0200, Andrea Bolognani wrote:
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/coding-style.rst | 53 +++++++++++------- docs/glib-adoption.rst | 123 +++++++++++++++++++++++++++-------------- 2 files changed, 114 insertions(+), 62 deletions(-)
diff --git a/docs/coding-style.rst b/docs/coding-style.rst index 151ea87b6a..15c3a0b22d 100644 --- a/docs/coding-style.rst +++ b/docs/coding-style.rst @@ -547,27 +547,38 @@ Attribute annotations Use the following annotations to help the compiler and/or static analysis tools understand the code better:
-+-------------------------------+------------------------------------------------------------+ -| Macro | Meaning | -+===============================+============================================================+ -| ``ATTRIBUTE_NONNULL`` | passing NULL for this parameter is not allowed | -+-------------------------------+------------------------------------------------------------+ -| ``ATTRIBUTE_PACKED`` | force a structure to be packed | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_FALLTHROUGH`` | allow code reuse by multiple switch cases | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_NO_INLINE`` | the function is mocked in the test suite | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_NORETURN`` | the function never returns | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_NULL_TERMINATED`` | last parameter must be NULL | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_PRINTF`` | validate that the formatting string matches parameters | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_UNUSED`` | parameter is unused in this implementation of the function | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_WARN_UNUSED_RESULT`` | the return value must be checked | -+-------------------------------+------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + + * - Macro + - Meaning + + * - ``ATTRIBUTE_NONNULL`` + - passing NULL for this parameter is not allowed
Well, the ascii-art version is more readable when looking at the text version.
On Thu, May 07, 2020 at 02:55:24PM +0200, Peter Krempa wrote:
On Thu, May 07, 2020 at 14:46:38 +0200, Andrea Bolognani wrote:
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/coding-style.rst | 53 +++++++++++------- docs/glib-adoption.rst | 123 +++++++++++++++++++++++++++-------------- 2 files changed, 114 insertions(+), 62 deletions(-)
diff --git a/docs/coding-style.rst b/docs/coding-style.rst index 151ea87b6a..15c3a0b22d 100644 --- a/docs/coding-style.rst +++ b/docs/coding-style.rst @@ -547,27 +547,38 @@ Attribute annotations Use the following annotations to help the compiler and/or static analysis tools understand the code better:
-+-------------------------------+------------------------------------------------------------+ -| Macro | Meaning | -+===============================+============================================================+ -| ``ATTRIBUTE_NONNULL`` | passing NULL for this parameter is not allowed | -+-------------------------------+------------------------------------------------------------+ -| ``ATTRIBUTE_PACKED`` | force a structure to be packed | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_FALLTHROUGH`` | allow code reuse by multiple switch cases | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_NO_INLINE`` | the function is mocked in the test suite | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_NORETURN`` | the function never returns | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_NULL_TERMINATED`` | last parameter must be NULL | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_PRINTF`` | validate that the formatting string matches parameters | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_UNUSED`` | parameter is unused in this implementation of the function | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_WARN_UNUSED_RESULT`` | the return value must be checked | -+-------------------------------+------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + + * - Macro + - Meaning + + * - ``ATTRIBUTE_NONNULL`` + - passing NULL for this parameter is not allowed
Well, the ascii-art version is more readable when looking at the text version.
I think there's probably a tradeoff to be had, based on the complexity and size of the table. For only simple tables where each line is less than 80 chars, and only 1 line high per row, then the ascii-art table is visually nicer. For tables where we're likely to exceed 80 chars, the list-table is probably better choice, otherwise things just get too wide. In this particular case, I think we didn't need a table at all in the first place. It would be fine as a "definition list". Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
On Thu, 2020-05-07 at 14:03 +0100, Daniel P. Berrangé wrote:
On Thu, May 07, 2020 at 02:55:24PM +0200, Peter Krempa wrote:
On Thu, May 07, 2020 at 14:46:38 +0200, Andrea Bolognani wrote:
-+-------------------------------+------------------------------------------------------------+ -| Macro | Meaning | -+===============================+============================================================+ -| ``ATTRIBUTE_NONNULL`` | passing NULL for this parameter is not allowed | -+-------------------------------+------------------------------------------------------------+
+.. list-table:: + :header-rows: 1 + + * - Macro + - Meaning + + * - ``ATTRIBUTE_NONNULL`` + - passing NULL for this parameter is not allowed
Well, the ascii-art version is more readable when looking at the text version.
I don't disagree.
I think there's probably a tradeoff to be had, based on the complexity and size of the table.
For only simple tables where each line is less than 80 chars, and only 1 line high per row, then the ascii-art table is visually nicer.
It's very unlikely that you'll have such a table: either you split the text across multiple lines to keep each under 80 chars, or you stick to a single line per row and end up with very long lines. The exception would probably be very simple two-rows tables, which as you mention below could be replaced with definition lists instead.
For tables where we're likely to exceed 80 chars, the list-table is probably better choice, otherwise things just get too wide.
Another thing to keep in mind is that using list-table makes the diffs when adding/removing rows, or even column, much more sane than they would be otherwise.
In this particular case, I think we didn't need a table at all in the first place. It would be fine as a "definition list".
For this specific case I think you're right. -- Andrea Bolognani / Red Hat / Virtualization
On Thu, May 07, 2020 at 02:46:38PM +0200, Andrea Bolognani wrote:
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/coding-style.rst | 53 +++++++++++------- docs/glib-adoption.rst | 123 +++++++++++++++++++++++++++-------------- 2 files changed, 114 insertions(+), 62 deletions(-)
diff --git a/docs/glib-adoption.rst b/docs/glib-adoption.rst index 62ddd7c61d..a5dca47f5e 100644 --- a/docs/glib-adoption.rst +++ b/docs/glib-adoption.rst @@ -53,44 +53,85 @@ The following libvirt APIs have been deleted already: ``VIR_STRDUP``, ``VIR_STRNDUP`` Prefer the GLib APIs ``g_strdup`` and ``g_strndup``.
-+-------------------------------+--------------------------------------+-------------------------------------------+ -| deleted version | GLib version | Notes | -+===============================+======================================+===========================================+ -| ``VIR_AUTOPTR`` | ``g_autoptr`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_AUTOCLEAN`` | ``g_auto`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_AUTOFREE`` | ``g_autofree`` | The GLib version does not use parentheses | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_AUTOUNREF`` | ``g_autoptr`` | The cleanup function needs to be defined | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_DEFINE_AUTOPTR_FUNC`` | ``G_DEFINE_AUTOPTR_CLEANUP_FUNC`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_DEFINE_AUTOCLEAN_FUNC`` | ``G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_STEAL_PTR`` | ``g_steal_pointer`` | ``a = f(&b)`` instead of ``f(a, b)`` | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_RETURN_PTR`` | ``return g_steal_pointer`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``ARRAY_CARDINALITY`` | ``G_N_ELEMENTS`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``ATTRIBUTE_FALLTHROUGH`` | ``G_GNUC_FALLTHROUGH`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``ATTRIBUTE_FMT_PRINTF`` | ``G_GNUC_PRINTF`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``ATTRIBUTE_NOINLINE`` | ``G_GNUC_NO_INLINE`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``ATTRIBUTE_NORETURN`` | ``G_GNUC_NORETURN`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``ATTRIBUTE_RETURN_CHECK`` | ``G_GNUC_WARN_UNUSED_RESULT`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``ATTRIBUTE_SENTINEL`` | ``G_GNUC_NULL_TERMINATED`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``ATTRIBUTE_UNUSED`` | ``G_GNUC_UNUSED`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_STRDUP`` | ``g_strdup`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``VIR_STRNDUP`` | ``g_strndup`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ -| ``virStrerror`` | ``g_strerror`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ +.. list-table:: + :header-rows: 1 + + * - deleted version + - GLib version + - Notes + + * - ``VIR_AUTOPTR`` + - ``g_autoptr`` + - + + * - ``VIR_AUTOCLEAN`` + - ``g_auto`` + - + + * - ``VIR_AUTOFREE`` + - ``g_autofree`` + - The GLib version does not use parentheses + + * - ``VIR_AUTOUNREF`` + - ``g_autoptr`` + - The cleanup function needs to be defined + + * - ``VIR_DEFINE_AUTOPTR_FUNC`` + - ``G_DEFINE_AUTOPTR_CLEANUP_FUNC`` + - + + * - ``VIR_DEFINE_AUTOCLEAN_FUNC`` + - ``G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC`` + - + + * - ``VIR_STEAL_PTR`` + - ``g_steal_pointer`` + - ``a = f(&b)`` instead of ``f(a, b)`` + + * - ``VIR_RETURN_PTR`` + - ``return g_steal_pointer`` + - + + * - ``ARRAY_CARDINALITY`` + - ``G_N_ELEMENTS`` + - + + * - ``ATTRIBUTE_FALLTHROUGH`` + - ``G_GNUC_FALLTHROUGH`` + - + + * - ``ATTRIBUTE_FMT_PRINTF`` + - ``G_GNUC_PRINTF`` + - + + * - ``ATTRIBUTE_NOINLINE`` + - ``G_GNUC_NO_INLINE`` + - + + * - ``ATTRIBUTE_NORETURN`` + - ``G_GNUC_NORETURN`` + - + + * - ``ATTRIBUTE_RETURN_CHECK`` + - ``G_GNUC_WARN_UNUSED_RESULT`` + - + + * - ``ATTRIBUTE_SENTINEL`` + - ``G_GNUC_NULL_TERMINATED`` + - + + * - ``ATTRIBUTE_UNUSED`` + - ``G_GNUC_UNUSED`` + - + + * - ``VIR_STRDUP`` + - ``g_strdup`` + - + + * - ``VIR_STRNDUP`` + - ``g_strndup`` + - + + * - ``virStrerror`` + - ``g_strerror`` + -
I'm wondering how long we actually need to bother keeping this text, given that it is talking about stuff we've already deleted. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
On Thu, May 07, 2020 at 14:04:44 +0100, Daniel Berrange wrote:
On Thu, May 07, 2020 at 02:46:38PM +0200, Andrea Bolognani wrote:
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/coding-style.rst | 53 +++++++++++------- docs/glib-adoption.rst | 123 +++++++++++++++++++++++++++-------------- 2 files changed, 114 insertions(+), 62 deletions(-)
diff --git a/docs/glib-adoption.rst b/docs/glib-adoption.rst index 62ddd7c61d..a5dca47f5e 100644 --- a/docs/glib-adoption.rst +++ b/docs/glib-adoption.rst @@ -53,44 +53,85 @@ The following libvirt APIs have been deleted already: ``VIR_STRDUP``, ``VIR_STRNDUP`` Prefer the GLib APIs ``g_strdup`` and ``g_strndup``.
[...]
I'm wondering how long we actually need to bother keeping this text, given that it is talking about stuff we've already deleted.
IMO we can purge those which don't have the definition present, which looks like it's all of them. Also when grepping random entries I've found that we mention VIR_STRDUP in a syntax check.
On Thu, 2020-05-07 at 14:04 +0100, Daniel P. Berrangé wrote:
I'm wondering how long we actually need to bother keeping this text, given that it is talking about stuff we've already deleted.
We've started using GLib six months ago. Do you think that's long enough to drop this page completely? I wouldn't mind. -- Andrea Bolognani / Red Hat / Virtualization
On Thu, May 07, 2020 at 03:36:55PM +0200, Andrea Bolognani wrote:
On Thu, 2020-05-07 at 14:04 +0100, Daniel P. Berrangé wrote:
I'm wondering how long we actually need to bother keeping this text, given that it is talking about stuff we've already deleted.
We've started using GLib six months ago. Do you think that's long enough to drop this page completely? I wouldn't mind.
Yeah, I think that'd be ok. For any other ideas of things we want to convert, we can create issues and tag them "bitesizedtask" Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/styleguide.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/styleguide.rst b/docs/styleguide.rst index 3162868fb7..34c5b1573a 100644 --- a/docs/styleguide.rst +++ b/docs/styleguide.rst @@ -77,6 +77,26 @@ which allows for 6 levels of headings Heading 6 ^^^^^^^^^ +Tables +====== + +Tables should be created using the ``list-table`` directive whenever +possible, as in + +:: + + .. list-table:: + :header-rows: 1 + + * - Option + - Description + + * - ``foo_enabled`` + - Whether or not ``foo`` should be enabled + + * - ``bar_user`` + - Which user to run ``bar`` as + Manual pages ============ -- 2.25.4
participants (3)
-
Andrea Bolognani -
Daniel P. Berrangé -
Peter Krempa