Skip to content

Commit 1050d2d

Browse files
vadmiumvadmium
committed
Issue #26462: Doc: reduce literal_block warnings, fix syntax highlighting.
Patch by Julien Palard.
1 parent 87ec85f commit 1050d2d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+329
-128
lines changed

‎Doc/distutils/examples.rst

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,9 @@ Let's take an example with a simple script::
245245

246246
setup(name='foobar')
247247

248-
Running the ``check`` command will display some warnings::
248+
Running the ``check`` command will display some warnings:
249+
250+
.. code-block:: shell-session
249251
250252
$ python setup.py check
251253
running check
@@ -274,7 +276,9 @@ For example, if the :file:`setup.py` script is changed like this::
274276
url='http://example.com', long_description=desc)
275277

276278
Where the long description is broken, ``check`` will be able to detect it
277-
by using the :mod:`docutils` parser::
279+
by using the :mod:`docutils` parser:
280+
281+
.. code-block:: shell-session
278282
279283
$ python setup.py check --restructuredtext
280284
running check
@@ -286,7 +290,9 @@ Reading the metadata
286290

287291
The :func:`distutils.core.setup` function provides a command-line interface
288292
that allows you to query the metadata fields of a project through the
289-
``setup.py`` script of a given project::
293+
``setup.py`` script of a given project:
294+
295+
.. code-block:: shell-session
290296
291297
$ python setup.py --name
292298
distribute

‎Doc/distutils/packageindex.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -233,7 +233,9 @@ in the root of the package besides :file:`setup.py`.
233233

234234
To prevent registering broken reStructuredText content, you can use the
235235
:program:`rst2html` program that is provided by the :mod:`docutils` package and
236-
check the ``long_description`` from the command line::
236+
check the ``long_description`` from the command line:
237+
238+
.. code-block:: shell-session
237239
238240
$ python setup.py --long-description | rst2html.py > output.html
239241

‎Doc/distutils/sourcedist.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -133,7 +133,9 @@ described above does not apply in this case.
133133

134134
The manifest template has one command per line, where each command specifies a
135135
set of files to include or exclude from the source distribution. For an
136-
example, again we turn to the Distutils' own manifest template::
136+
example, again we turn to the Distutils' own manifest template:
137+
138+
.. code-block:: none
137139
138140
include *.txt
139141
recursive-include examples *.txt *.py

‎Doc/extending/building.rst

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,9 @@ Since distutils also supports creation of binary packages, users don't
5555
necessarily need a compiler and distutils to install the extension.
5656
5757
A distutils package contains a driver script, :file:`setup.py`. This is a plain
58-
Python file, which, in the most simple case, could look like this::
58+
Python file, which, in the most simple case, could look like this:
59+
60+
.. code-block:: python3
5961
6062
from distutils.core import setup, Extension
6163
@@ -96,7 +98,9 @@ file, :file:`demo.c`.
9698

9799
In many cases, building an extension is more complex, since additional
98100
preprocessor defines and libraries may be needed. This is demonstrated in the
99-
example below. ::
101+
example below.
102+
103+
.. code-block:: python3
100104
101105
from distutils.core import setup, Extension
102106
@@ -161,4 +165,3 @@ commands can be used to do so. ::
161165
python setup.py bdist_wininst
162166
python setup.py bdist_rpm
163167
python setup.py bdist_dumb
164-

‎Doc/extending/embedding.rst

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -155,7 +155,9 @@ script, such as:
155155
c = c + b
156156
return c
157157
158-
then the result should be::
158+
then the result should be:
159+
160+
.. code-block:: shell-session
159161
160162
$ call multiply multiply 3 2
161163
Will compute 3 times 2
@@ -289,16 +291,20 @@ available). This script has several options, of which the following will
289291
be directly useful to you:
290292

291293
* ``pythonX.Y-config --cflags`` will give you the recommended flags when
292-
compiling::
294+
compiling:
295+
296+
.. code-block:: shell-session
293297
294-
$ /opt/bin/python3.4-config --cflags
295-
-I/opt/include/python3.4m -I/opt/include/python3.4m -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes
298+
$ /opt/bin/python3.4-config --cflags
299+
-I/opt/include/python3.4m -I/opt/include/python3.4m -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes
296300
297301
* ``pythonX.Y-config --ldflags`` will give you the recommended flags when
298-
linking::
302+
linking:
303+
304+
.. code-block:: shell-session
299305
300-
$ /opt/bin/python3.4-config --ldflags
301-
-L/opt/lib/python3.4/config-3.4m -lpthread -ldl -lutil -lm -lpython3.4m -Xlinker -export-dynamic
306+
$ /opt/bin/python3.4-config --ldflags
307+
-L/opt/lib/python3.4/config-3.4m -lpthread -ldl -lutil -lm -lpython3.4m -Xlinker -export-dynamic
302308
303309
.. note::
304310
To avoid confusion between several Python installations (and especially

‎Doc/extending/extending.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -792,7 +792,9 @@ the format string is empty, it returns ``None``; if it contains exactly one
792792
format unit, it returns whatever object is described by that format unit. To
793793
force it to return a tuple of size 0 or one, parenthesize the format string.
794794

795-
Examples (to the left the call, to the right the resulting Python value)::
795+
Examples (to the left the call, to the right the resulting Python value):
796+
797+
.. code-block:: none
796798
797799
Py_BuildValue("") None
798800
Py_BuildValue("i", 123) 123
@@ -1348,4 +1350,3 @@ code distribution).
13481350
13491351
.. [#] These guarantees don't hold when you use the "old" style calling convention ---
13501352
this is still found in much existing code.
1351-

‎Doc/extending/newtypes.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -209,7 +209,9 @@ That's it! All that remains is to build it; put the above code in a file called
209209
setup(name="noddy", version="1.0",
210210
ext_modules=[Extension("noddy", ["noddy.c"])])
211211

212-
in a file called :file:`setup.py`; then typing ::
212+
in a file called :file:`setup.py`; then typing
213+
214+
.. code-block:: shell-session
213215
214216
$ python setup.py build
215217
@@ -1513,4 +1515,3 @@ might be something like the following::
15131515
.. [#] Even in the third version, we aren't guaranteed to avoid cycles. Instances of
15141516
string subclasses are allowed and string subclasses could allow cycles even if
15151517
normal strings don't.
1516-

‎Doc/faq/extending.rst

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -146,7 +146,9 @@ this object to :data:`sys.stdout` and :data:`sys.stderr`. Call print_error, or
146146
just allow the standard traceback mechanism to work. Then, the output will go
147147
wherever your ``write()`` method sends it.
148148

149-
The easiest way to do this is to use the :class:`io.StringIO` class::
149+
The easiest way to do this is to use the :class:`io.StringIO` class:
150+
151+
.. code-block:: pycon
150152
151153
>>> import io, sys
152154
>>> sys.stdout = io.StringIO()
@@ -156,7 +158,9 @@ The easiest way to do this is to use the :class:`io.StringIO` class::
156158
foo
157159
hello world!
158160
159-
A custom object to do the same would look like this::
161+
A custom object to do the same would look like this:
162+
163+
.. code-block:: pycon
160164
161165
>>> import io, sys
162166
>>> class StdoutCatcher(io.TextIOBase):
@@ -222,11 +226,15 @@ How do I debug an extension?
222226
When using GDB with dynamically loaded extensions, you can't set a breakpoint in
223227
your extension until your extension is loaded.
224228

225-
In your ``.gdbinit`` file (or interactively), add the command::
229+
In your ``.gdbinit`` file (or interactively), add the command:
230+
231+
.. code-block:: none
226232
227233
br _PyImport_LoadDynamicModule
228234
229-
Then, when you run GDB::
235+
Then, when you run GDB:
236+
237+
.. code-block:: shell-session
230238
231239
$ gdb /local/bin/python
232240
gdb) run myscript.py

‎Doc/howto/clinic.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,9 @@ Let's dive in!
152152
For my example I'm using ``_pickle.Pickler.dump()``.
153153

154154
2. If the call to the ``PyArg_Parse`` function uses any of the
155-
following format units::
155+
following format units:
156+
157+
.. code-block:: none
156158
157159
O&
158160
O!

‎Doc/howto/logging-cookbook.rst

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -377,7 +377,9 @@ An example of using these two classes follows (imports omitted)::
377377
root.warning('Look out!')
378378
listener.stop()
379379

380-
which, when run, will produce::
380+
which, when run, will produce:
381+
382+
.. code-block:: none
381383
382384
MainThread: Look out!
383385
@@ -1860,7 +1862,9 @@ script, ``chowntest.py``::
18601862
logger = logging.getLogger('mylogger')
18611863
logger.debug('A debug message')
18621864

1863-
To run this, you will probably need to run as ``root``::
1865+
To run this, you will probably need to run as ``root``:
1866+
1867+
.. code-block:: shell-session
18641868
18651869
$ sudo python3.3 chowntest.py
18661870
$ cat chowntest.log
@@ -2485,7 +2489,9 @@ via ``stderr`` and once via ``stdout``). After the ``with`` statement's
24852489
completion, the status is as it was before so message #6 appears (like message
24862490
#1) whereas message #7 doesn't (just like message #2).
24872491

2488-
If we run the resulting script, the result is as follows::
2492+
If we run the resulting script, the result is as follows:
2493+
2494+
.. code-block:: shell-session
24892495
24902496
$ python logctx.py
24912497
1. This should appear just once on stderr.
@@ -2495,12 +2501,16 @@ If we run the resulting script, the result is as follows::
24952501
6. This should appear just once on stderr.
24962502
24972503
If we run it again, but pipe ``stderr`` to ``/dev/null``, we see the following,
2498-
which is the only message written to ``stdout``::
2504+
which is the only message written to ``stdout``:
2505+
2506+
.. code-block:: shell-session
24992507
25002508
$ python logctx.py 2>/dev/null
25012509
5. This should appear twice - once on stderr and once on stdout.
25022510
2503-
Once again, but piping ``stdout`` to ``/dev/null``, we get::
2511+
Once again, but piping ``stdout`` to ``/dev/null``, we get:
2512+
2513+
.. code-block:: shell-session
25042514
25052515
$ python logctx.py >/dev/null
25062516
1. This should appear just once on stderr.

0 commit comments

Comments
 (0)