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
  1. This is a numbered list.
  2. It has two items as well.
  3. This is an autonumbered list?
  4. Does it start at 1 or 3??
    1. We can also make sublists.
    2. What an idea!
term (up to a line of text)

The definition of term is term, which must be indented

But it can have multiple paragraphs!

next term
Is described
These lines have
breaks that are perfectly
preserved.

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
Paragraph 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

The GNU logo

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!

  • A list of
  • short items
  • that should be
  • displayed
  • horizontally
this.py
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