-
Notifications
You must be signed in to change notification settings - Fork 297
/
blocks.rst
282 lines (198 loc) · 8.23 KB
/
blocks.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
..
Copyright (c) 2021 Pradyun Gedam
Licensed under Creative Commons Attribution-ShareAlike 4.0 International License
SPDX-License-Identifier: CC-BY-SA-4.0
======
Blocks
======
Block Quotes
============
Block quotes consist of indented body elements:
My theory by A. Elk. Brackets Miss, brackets. This theory goes
as follows and begins now. All brontosauruses are thin at one
end, much much thicker in the middle and then thin again at the
far end. That is my theory, it is mine, and belongs to me and I
own it, and what it is too.
-- Anne Elk (Miss)
Epigraph
--------
https://docutils.sourceforge.io/docs/ref/rst/directives.html#epigraph
.. epigraph::
My theory by A. Elk. Brackets Miss, brackets. This theory goes
as follows and begins now. All brontosauruses are thin at one
end, much much thicker in the middle and then thin again at the
far end. That is my theory, it is mine, and belongs to me and I
own it, and what it is too.
-- Anne Elk (Miss)
Pull quotes
-----------
https://docutils.sourceforge.io/docs/ref/rst/directives.html#pull-quote
.. pull-quote::
My theory by A. Elk. Brackets Miss, brackets. This theory goes
as follows and begins now. All brontosauruses are thin at one
end, much much thicker in the middle and then thin again at the
far end. That is my theory, it is mine, and belongs to me and I
own it, and what it is too.
-- Anne Elk (Miss)
Highlights
----------
https://docutils.sourceforge.io/docs/ref/rst/directives.html#highlights
.. highlights::
My theory by A. Elk. Brackets Miss, brackets. This theory goes
as follows and begins now. All brontosauruses are thin at one
end, much much thicker in the middle and then thin again at the
far end. That is my theory, it is mine, and belongs to me and I
own it, and what it is too.
-- Anne Elk (Miss)
Line Blocks
===========
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks
This is a normal text paragraph.
| This is a line block. It ends with a blank line.
| Each new line begins with a vertical bar ("|").
| Line breaks and initial indents are preserved.
| Continuation lines are wrapped portions of long lines;
they begin with a space in place of the vertical bar.
| The left edge of a continuation line need not be aligned with
the left edge of the text above it.
| This is a second line block.
|
| Blank lines are permitted internally, but they must begin with a "|".
This is a normal text paragraph again.
Monospace Blocks
================
Sphinx supports many kinds of monospace blocks. This section is meant to
showcase *all* of them that are known to the author of this page, at the time of
writing.
Production List
---------------
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-productionlist
This directive is used to enclose a group of productions. Each production is given on a single line and consists of a name, separated by a colon from the following definition.
This just shows up as a vanilla ``<pre>``, which is... both nice and a bit
annoying.
.. productionlist::
try_stmt: try1_stmt | try2_stmt
try1_stmt: "try" ":" `suite`
: ("except" [`expression` ["," `target`]] ":" `suite`)+
: ["else" ":" `suite`]
: ["finally" ":" `suite`]
try2_stmt: "try" ":" `suite`
: "finally" ":" `suite`
: "this-is-intentionally-very-stupidly-long-to-make-sure-that-this-has-a-proper-scrollbar"
Literal Blocks
--------------
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks
contains a block of text where line breaks and whitespace are significant and must be preserved
This is a normal text paragraph. The next paragraph is a code sample::
It is not processed in any way, except
that the indentation is removed.
It can span multiple lines.
This is a normal text paragraph again.
They can be quoted without indentation::
>> Great idea!
>
> Why didn't I think of that?
.. literalinclude:: ../../src/furo/__init__.py
:language: python
:caption: Literal includes can also have captions.
:linenos:
:lines: 10-20
Doctest Blocks
--------------
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#doctest-blocks
Doctest blocks are interactive Python sessions cut-and-pasted into docstrings. They are meant to illustrate usage by example, and provide an elegant and powerful testing environment via the doctest module in the Python standard library.
.. note::
This is fine.
>>> print('Python-specific usage examples; begun with ">>>"')
Python-specific usage examples; begun with ">>>"
>>> print("(cut and pasted from interactive Python sessions)")
(cut and pasted from interactive Python sessions)
>>> print("This is an intentionally very long line because I want to make sure that we are handling scrollable code blocks correctly.")
This is an intentionally very long line because I want to make sure that we are handling scrollable code blocks correctly.
Parsed Literals
---------------
https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal-block
It is equivalent to a line block with different rendering: typically in a typewriter/monospaced typeface, like an ordinary literal block. Parsed literal blocks are useful for adding hyperlinks to code examples.
.. parsed-literal::
# parsed-literal test
curl -O http://someurl/release-0.1.0.tar-gz
echo "This is an intentionally very long line because I want to make sure that we are handling scrollable code blocks correctly."
asyncio.set_event_loop_policy(
asyncio.WindowsSelectorEventLoopPolicy()
)
With inline code
~~~~~~~~~~~~~~~~
Here's a parsed literal containing nested inline code:
.. parsed-literal::
:obj:`asyncio.set_event_loop_policy`\ (
:obj:`asyncio.WindowsSelectorEventLoopPolicy`\ ()
)
Code Block
----------
https://docutils.sourceforge.io/docs/ref/rst/directives.html#code
The "code" directive constructs a literal block [containing code].
This has an alias of ``code-block``.
.. code-block:: python
:linenos:
from typing import Iterator
# This is an example
class Math:
@staticmethod
def fib(n: int) -> Iterator[int]:
"""Fibonacci series up to n"""
a, b = 0, 1
while a < n:
yield a
a, b = b, a + b
result = sum(Math.fib(42))
print("The answer is {}".format(result))
With caption
~~~~~~~~~~~~
.. code-block:: json
:caption: Code Blocks can have captions, which also adds a link to it.
{
"session_name": "shorthands",
"windows": [
{
"panes": [
{
"shell_command": "echo 'This is an intentionally very long line because I want to make sure that we are handling scrollable code blocks correctly.'"
}
],
"window_name": "long form"
}
]
}
With line numbers
~~~~~~~~~~~~~~~~~
.. code-block:: python
:linenos:
:emphasize-lines: 3,5
def some_function():
interesting = False
print("This line is highlighted.")
print("This one is not...")
print("...but this one is.")
print(
"This is an intentionally very long line because I want to make sure that we are handling scrollable code blocks correctly."
)
With ``none`` highlighting
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: none
# Taken from https://en.wikipedia.org/wiki/Pseudocode#Example
algorithm ford-fulkerson is
input: Graph G with flow capacity c,
source node s,
sink node t
output: Flow f such that f is maximal from s to t
(Note that f(u,v) is the flow from node u to node v, and c(u,v) is the flow capacity from node u to node v)
for each edge (u, v) in GE do
f(u, v) ← 0
f(v, u) ← 0
while there exists a path p from s to t in the residual network Gf do
let cf be the flow capacity of the residual network Gf
cf(p) ← min{cf(u, v) | (u, v) in p}
for each edge (u, v) in p do
f(u, v) ← f(u, v) + cf(p)
f(v, u) ← −f(u, v)
return f