PAGE 1¶
Testing out some intersphinx thingy does this cross ref? io.open()
Paragraphs are things!
We can do italics, boldface, and code samples
! Or we can do
thisisoneword!
- This is a bulleted list.
- It has two items, the second item uses two lines
- This is a numbered list.
- It has two items as well.
- This is an autonumbered list?
- Does it start at 1 or 3??
- We can also make sublists.
- What an idea!
- term (up to a line of text)
The definition of term is
term
, which must be indentedBut it can have multiple paragraphs!
- next term
- Is described
This is normal text, but this is a code sample (a literal block):
It is not processed in any way, except
that the indentation is removed!
It can span many lines.
But now it is over and this is a normal paragraph again.
We can also do “doctest” blocks:
>>> 1 + 1
2
Ok well making tables is a bit more annoying
Header row, column 1 (header rows optional) | Header 2 | Header 3 | Header 4 |
---|---|---|---|
body row 1, column 1 | column 2 | column 3 | column 4 |
body row 2 | … | … | … |
But there are simpler tables too:
A | B | A and B |
---|---|---|
False | False | False |
True | False | False |
False | True | False |
True | True | True |
I think you can make links like this
Or we can do it like this.
We can do sections!
PART 1¶
Chapter 1¶
Section 1¶
Subsection 1¶
SubSubSection 1¶
WOW! This follows the Python’s Guide for Documenting
And if we modify the Table of Contents in index.rst, we can get these sections to show up on the main page!
Field Lists are sequences of fields
fieldname: | Field content |
---|
They are commonly used in Python documentation:
def my_function(my_arg, my_other_arg):
"""A function just for me!
:param my_arg: The first of my arguments.
:param my_other_arg: The second of my arguments.
:returns: A message (just for me, of course).
"""
Roles are things? Oh I see, we can also do emphasis, strong, literal
, subscript, superscript, and
title-reference.
Then there are directives which sound cool. Like this one: that gives Python-style documentation for a function.
-
some.module.name.
foo
(x)¶ -
some.module.name.
foo
(y, z) Return a line of text input from the user
Attention
There’s the attention directive
Caution
There’s the caution directive
Danger
There’s the danger directive
Error
There’s the error directive
Hint
There’s the hint directive
Important
There’s the important directive
Note
There’s the note directive
Tip
There’s the tip directive
Warning
There’s the warning directive
and the generic
There’s the admonition directive
Which maybe needs more stuff? Oh no, this one lets you put your own title.
They note that really only “note” and “warning” are usually formatted. Obvs the default also has “danger”/”error” as well.
We can also do
Do I need to break stuff up here?
Topic1
This is a topic?
What if I keep going?
Oh and then there are sidebars, which maybe actually go to the side??? That would be cool I’m trying to write enough text to test this…
Maybe I need text after it! Let’s try that!
Aha! That worked, now there’s a sidebar next to my main stuff! COOL
An important one might be Images
How do I get text? Nvm
We can do Footnotes! [1] Or noted-foots, as I like to call them [2] !
Similarly, we can do references. [Ref]
Then there are Roles.
I think they help with cross-referencing?
-
install
()¶ This function installs a handler for every signal known by the
signal
module. See the section Section 1 for more information. Changes! Ok so we use:ref:
to do references to things.
We can do math! \(a^2 + b^2 = c^2\). Neat!
|
|
|
1 2 3 4 5 | def some_function():
interesting = False
print 'This line is highlighted.'
print 'This one is not...'
print '...but this one is.'
|
Footnotes
[1] | This is a footnote. |
[2] | This is a noted foot. |
References
[Ref] | A totally legit reference (2020) Eric’s Journal of Pretty Good Stuff |