[Python-checkins] cpython (3.5): Issue #28755: Improve syntax highlighting in Arg Clinic howto
martin.panter
python-checkins at python.org
Fri Dec 9 23:23:10 EST 2016
https://hg.python.org/cpython/rev/3795ba7490b1
changeset: 105562:3795ba7490b1
branch: 3.5
user: Martin Panter <vadmium+py at gmail.com>
date: Sat Dec 10 04:10:45 2016 +0000
summary:
Issue #28755: Improve syntax highlighting in Arg Clinic howto
files:
Doc/howto/clinic.rst | 44 +++++++++++++++++++++----------
1 files changed, 29 insertions(+), 15 deletions(-)
diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
--- a/Doc/howto/clinic.rst
+++ b/Doc/howto/clinic.rst
@@ -1,3 +1,5 @@
+.. highlightlang:: c
+
**********************
Argument Clinic How-To
**********************
@@ -78,17 +80,23 @@
========================
Argument Clinic ships with CPython; you'll find it in ``Tools/clinic/clinic.py``.
-If you run that script, specifying a C file as an argument::
+If you run that script, specifying a C file as an argument:
- % python3 Tools/clinic/clinic.py foo.c
+.. code-block:: shell-session
+
+ $ python3 Tools/clinic/clinic.py foo.c
Argument Clinic will scan over the file looking for lines that
-look exactly like this::
+look exactly like this:
+
+.. code-block:: none
/*[clinic input]
When it finds one, it reads everything up to a line that looks
-exactly like this::
+exactly like this:
+
+.. code-block:: none
[clinic start generated code]*/
@@ -99,7 +107,9 @@
When Argument Clinic parses one of these blocks, it
generates output. This output is rewritten into the C file
immediately after the block, followed by a comment containing a checksum.
-The Argument Clinic block now looks like this::
+The Argument Clinic block now looks like this:
+
+.. code-block:: none
/*[clinic input]
... clinic input goes here ...
@@ -378,9 +388,7 @@
12. Save and close the file, then run ``Tools/clinic/clinic.py`` on
it. With luck everything worked---your block now has output, and
a ``.c.h`` file has been generated! Reopen the file in your
- text editor to see:
-
- .. code-block:: c
+ text editor to see::
/*[clinic input]
_pickle.Pickler.dump
@@ -402,9 +410,7 @@
For readability, most of the glue code has been generated to a ``.c.h``
file. You'll need to include that in your original ``.c`` file,
- typically right after the clinic module block:
-
- .. code-block:: c
+ typically right after the clinic module block::
#include "clinic/_pickle.c.h"
@@ -1028,7 +1034,9 @@
value), then the generated code will propagate the error. Otherwise it will
encode the value you return like normal.
-Currently Argument Clinic supports only a few return converters::
+Currently Argument Clinic supports only a few return converters:
+
+.. code-block:: none
bool
int
@@ -1607,7 +1615,9 @@
#endif /* HAVE_FUNCTIONNAME */
And then in the ``PyMethodDef`` structure at the bottom the existing code
-will have::
+will have:
+
+.. code-block:: none
#ifdef HAVE_FUNCTIONNAME
{'functionname', ... },
@@ -1657,7 +1667,9 @@
because that could be deactivated by the ``#ifdef``. (That's the whole point!)
In this situation, Argument Clinic writes the extra code to the "buffer" destination.
-This may mean that you get a complaint from Argument Clinic::
+This may mean that you get a complaint from Argument Clinic:
+
+.. code-block:: none
Warning in file "Modules/posixmodule.c" on line 12357:
Destination buffer 'buffer' not empty at end of file, emptying.
@@ -1677,7 +1689,9 @@
to run Python blocks lets you use Python as a Python preprocessor!
Since Python comments are different from C comments, Argument Clinic
-blocks embedded in Python files look slightly different. They look like this::
+blocks embedded in Python files look slightly different. They look like this:
+
+.. code-block:: python3
#/*[python input]
#print("def foo(): pass")
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list