From fe334f79a9a9fec1f174fe0c064999a11e6d073d Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Wed, 13 Jul 2022 15:34:18 +0200 Subject: [PATCH 1/5] Add a quick reference for rst markup. --- documentation/markup.rst | 40 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index c657770217..99d20a47f5 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -10,6 +10,29 @@ This document describes the custom reStructuredText markup introduced by Sphinx to support Python documentation and how it should be used. +Quick Reference +=============== + +This table summarizes which markup should be used for some commonly used +elements: + +================ ========================================= ==================== +Element Markup See also +================ ========================================= ==================== +arguments ``*arg*`` :ref:`inline-markup` +variables ````var```` :ref:`inline-markup` +literals ````0````, ````[]```` :ref:`inline-markup` +True/False/None ````True````, ````False````, ````None```` :ref:`inline-markup` +code snippets ````print('hello world')```` :ref:`inline-markup` +functions ``:func:`sorted``` :ref:`roles` +func definitions ``.. function:: func(args)`` :ref:`directives` +reference labels ``.. _label-name:`` :ref:`doc-ref-role` +internal ref ``:ref:`label-name``` :ref:`doc-ref-role` +external links ```Link text `_`` :ref:`hyperlinks` +comments ``.. a comment`` :ref:`comments` +================ ========================================= ==================== + + .. _rst-primer: reStructuredText Primer @@ -34,6 +57,7 @@ chunks of text separated by one or more blank lines. As in Python, indentation is significant in reST, so all lines of the same paragraph must be left-aligned to the same level of indentation. +.. _inline-markup: Inline markup ------------- @@ -42,7 +66,9 @@ The standard reST inline markup is quite simple: use * one asterisk: ``*text*`` for emphasis (italics), * two asterisks: ``**text**`` for strong emphasis (boldface), and -* backquotes: ````text```` for code samples. +* backquotes: ````text```` for code samples, variables, and literals. + +Italic is also used for function and method arguments (``*arg*``). If asterisks or backquotes appear in running text and could be confused with inline markup delimiters, they have to be escaped with a backslash. @@ -132,6 +158,7 @@ The handling of the ``::`` marker is smart: That way, the second sentence in the above example's first paragraph would be rendered as "The next paragraph is a code sample:". +.. _hyperlinks: Hyperlinks ---------- @@ -185,6 +212,7 @@ indentation. (There needs to be a blank line between explicit markup and normal paragraphs. This may all sound a bit complicated, but it is intuitive enough when you write it.) +.. _directives: Directives ---------- @@ -229,6 +257,7 @@ body at the bottom of the document after a "Footnotes" rubric heading, like so:: You can also explicitly number the footnotes for better context. +.. _comments: Comments -------- @@ -236,6 +265,10 @@ Comments Every explicit markup block which isn't a valid markup construct (like the footnotes above) is regarded as a comment. +Comments are generally preceeded by ``..``:: + + .. This is a comment + Source encoding --------------- @@ -636,9 +669,10 @@ The file name is relative to the current file's path. Documentation-specific include files should be placed in the ``Doc/includes`` subdirectory. .. _rest-inline-markup: +.. _roles: -Inline markup -------------- +Roles +----- As said before, Sphinx uses interpreted text roles to insert semantic markup in documents. From 38af60313757089c186588ad0f7418a61ffb717f Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Wed, 3 Aug 2022 01:02:44 +0200 Subject: [PATCH 2/5] Address review comments. --- documentation/markup.rst | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index 99d20a47f5..e514ad0a46 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -16,21 +16,22 @@ Quick Reference This table summarizes which markup should be used for some commonly used elements: -================ ========================================= ==================== -Element Markup See also -================ ========================================= ==================== -arguments ``*arg*`` :ref:`inline-markup` -variables ````var```` :ref:`inline-markup` -literals ````0````, ````[]```` :ref:`inline-markup` -True/False/None ````True````, ````False````, ````None```` :ref:`inline-markup` -code snippets ````print('hello world')```` :ref:`inline-markup` -functions ``:func:`sorted``` :ref:`roles` -func definitions ``.. function:: func(args)`` :ref:`directives` -reference labels ``.. _label-name:`` :ref:`doc-ref-role` -internal ref ``:ref:`label-name``` :ref:`doc-ref-role` -external links ```Link text `_`` :ref:`hyperlinks` -comments ``.. a comment`` :ref:`comments` -================ ========================================= ==================== +===================== =========================================== ==================== +Element Markup See also +===================== =========================================== ==================== +arguments/parameters ``*arg*`` :ref:`inline-markup` +vars/literals/code ````var````, ````42````, ````len(s) - 1```` :ref:`inline-markup` +True/False/None ````True````, ````False````, ````None```` :ref:`inline-markup` +functions ``:func:`sorted``` :ref:`roles` +func definitions ``.. function:: func(args)`` :ref:`directives` +reference labels ``.. _label-name:`` :ref:`doc-ref-role` +internal ref ``:ref:`label-name``` :ref:`doc-ref-role` +external links ```Link text `_`` :ref:`hyperlinks` +roles w/ custom text ``:role:`custom text ``` :ref:`roles` +roles w/o link ``:role:`!target``` :ref:`roles` +roles w/o first part ``:role:`~hidden.hidden.visible``` :ref:`roles` +comments ``.. a comment`` :ref:`comments` +===================== =========================================== ==================== .. _rst-primer: From fe73d052095f5a3690aeffc4b78e9a82c3b0d233 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Thu, 4 Aug 2022 03:16:00 +0200 Subject: [PATCH 3/5] Address review comments. --- documentation/markup.rst | 46 +++++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 22 deletions(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index e514ad0a46..013d24dc9f 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -16,22 +16,22 @@ Quick Reference This table summarizes which markup should be used for some commonly used elements: -===================== =========================================== ==================== -Element Markup See also -===================== =========================================== ==================== -arguments/parameters ``*arg*`` :ref:`inline-markup` -vars/literals/code ````var````, ````42````, ````len(s) - 1```` :ref:`inline-markup` -True/False/None ````True````, ````False````, ````None```` :ref:`inline-markup` -functions ``:func:`sorted``` :ref:`roles` -func definitions ``.. function:: func(args)`` :ref:`directives` -reference labels ``.. _label-name:`` :ref:`doc-ref-role` -internal ref ``:ref:`label-name``` :ref:`doc-ref-role` -external links ```Link text `_`` :ref:`hyperlinks` -roles w/ custom text ``:role:`custom text ``` :ref:`roles` -roles w/o link ``:role:`!target``` :ref:`roles` -roles w/o first part ``:role:`~hidden.hidden.visible``` :ref:`roles` -comments ``.. a comment`` :ref:`comments` -===================== =========================================== ==================== +======================= =========================================== ==================== +Element Markup See also +======================= =========================================== ==================== +arguments/parameters ``*arg*`` :ref:`inline-markup` +variables/literals/code ````foo````, ````42````, ````len(s) - 1```` :ref:`inline-markup` +True/False/None ````True````, ````False````, ````None```` :ref:`inline-markup` +functions definitions ``.. function:: print(*args)`` :ref:`directives` +functions references ``:func:`print``` :ref:`roles` +reference labels ``.. _label-name:`` :ref:`doc-ref-role` +internal references ``:ref:`label-name``` :ref:`doc-ref-role` +external links ```Link text `_`` :ref:`hyperlinks` +roles w/ custom text ``:role:`custom text ``` :ref:`roles` +roles w/ only last part ``:role:`~hidden.hidden.visible``` :ref:`roles` +roles w/o link ``:role:`!target``` :ref:`roles` +comments ``.. a comment`` :ref:`comments` +======================= =========================================== ==================== .. _rst-primer: @@ -263,10 +263,8 @@ You can also explicitly number the footnotes for better context. Comments -------- -Every explicit markup block which isn't a valid markup construct (like the -footnotes above) is regarded as a comment. - -Comments are generally preceeded by ``..``:: +Every explicit markup block (starting with :literal:`.. \ `) which isn't a +:ref:`valid markup construct ` is regarded as a comment:: .. This is a comment @@ -678,8 +676,12 @@ Roles As said before, Sphinx uses interpreted text roles to insert semantic markup in documents. -Names of local variables, such as function/method arguments, are an exception, -they should be marked simply with ``*var*``. +There are a couple of cases where roles can be omitted in favor of +simpler markup: + +* Function and method arguments can be marked with ``*arg*``. +* ``True``, ``False``, ``None``, and variables can be marked with + :literal:`\`\`...```. For all other roles, you have to write ``:rolename:`content```. From 5b35d544efcfcc25af8dad1e21a1f0028984f568 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sat, 6 Aug 2022 01:25:26 +0200 Subject: [PATCH 4/5] Address review comments. Co-authored-by: CAM Gerlach --- documentation/markup.rst | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index 013d24dc9f..5e74e40627 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -69,8 +69,6 @@ The standard reST inline markup is quite simple: use * two asterisks: ``**text**`` for strong emphasis (boldface), and * backquotes: ````text```` for code samples, variables, and literals. -Italic is also used for function and method arguments (``*arg*``). - If asterisks or backquotes appear in running text and could be confused with inline markup delimiters, they have to be escaped with a backslash. @@ -673,17 +671,15 @@ include files should be placed in the ``Doc/includes`` subdirectory. Roles ----- -As said before, Sphinx uses interpreted text roles to insert semantic markup in -documents. - -There are a couple of cases where roles can be omitted in favor of -simpler markup: +As :ref:`previously mentioned `, Sphinx uses +interpreted text roles of the form ``:rolename:`content``` +to insert semantic markup in documents. -* Function and method arguments can be marked with ``*arg*``. -* ``True``, ``False``, ``None``, and variables can be marked with - :literal:`\`\`...```. +In the CPython documentation, there are a few common cases +where simpler markup should be used: -For all other roles, you have to write ``:rolename:`content```. +* ``*arg*`` (rendered as *arg*) for function and method arguments. +* ````True````/````False````/````None```` for ``True``/``False``/``None``. There are some additional facilities that make cross-referencing roles more versatile: From c39d593c7b69b87488256d0c6a18c365e450000b Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sat, 6 Aug 2022 01:39:26 +0200 Subject: [PATCH 5/5] Apply suggestions from code review. Co-authored-by: CAM Gerlach --- documentation/markup.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index 5e74e40627..47172eb3bc 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -671,11 +671,11 @@ include files should be placed in the ``Doc/includes`` subdirectory. Roles ----- -As :ref:`previously mentioned `, Sphinx uses +As :ref:`previously mentioned `, Sphinx uses interpreted text roles of the form ``:rolename:`content``` to insert semantic markup in documents. -In the CPython documentation, there are a few common cases +In the CPython documentation, there are a couple common cases where simpler markup should be used: * ``*arg*`` (rendered as *arg*) for function and method arguments.