papyri.examples

Examples Modules Heading 1

This module contains examples, none of the functions, classes or other attribute should have any effects when called. Paragraphs should be able to contain plain links, or link via directives: papyri

Heading 2

link to numpy.sin , numpy:sin numpy.linspace

Heading 3

heading 4

FieldList

In my understanding FieldList should in general not happen in the final Documents, they are supposed to be processed by the software reading them, and typically appear at the beginning of directive.

fieldlistitem

at least that the name tree sitter rst give it.

another

is another fieldlistItem in this field list and it's description

Enumeration and unordered lists

Enumeration list.

• item 1

• item 2

• item 3

Unordered list

• item 1

• item 2

• item 3

Definition Lists

term 1

Definition 1.

term 2

Definition 2, paragraph 1.

Definition 2, paragraph 2.

Admonitions

This is a link to Jupyter website

Code (title 2)

from package import module
module.call("string")

Math

Math should both work as standalone formulas that takes a block:

More complex formula:

But should be also available in inline context, for example we know that ${\pi }^2\simeq 10$, and that $1+1=10$ when counting in binary.

Literal Blocks (verbatim)

This should be a verb-
-batim block

This is a Transition:

This is a block quote, to do, we know that Attributions are not supported right now.

"We have weaponed the Tab Key"

Substitutions

This text uses a substitution: Papyri is the package name.

Citation references

Citation references link inline mentions to a matching bibliographic citation defined elsewhere in the document, typically at the bottom of a docstring. A reference looks like [CIT2002], and multiple references such as [Smith2020] and [Jones1999] can appear in the same paragraph. Labels follow the RST "simple reference name" rule (letters, digits, hyphens).

Quotes

Quotes are not implemented yet in the parser, this section below will appear empty

Directive

Please have a look at the source to see the custom directives. The file example/papyri.toml also show how to register a custom callable for a custom directive handler

[global.directives]
mydirective='papyri.examples:_mydirective_handler'

.. directive:: those are the **arguments**, passed as a ``string``
   {
     "the": "",
     "flags": "",
     "and": "Here",
     "are": "some",
     "option": "field"
   }
   Beyond this is the core of the directive, it will be stored as a raw string
   in the value of Directive without the leading indentation. It is the
   responsibility of the directive handler to parse the directive and return
   corresponding ast nodes for further processing.

those are the arguments, passed as a string

_mydirective_handler(
args='those are the **arguments**, passed as a ``string``',
options={'the': '', 'flags': '', 'and': 'Here', 'are': 'some', 'option': 'field'}, 
value='Beyond this is the core of the directive, it will be stored as a raw string\nin the value of Directive without the leading indentation. It is the\nresponsibility of the directive handler to parse the directive and return\ncorresponding ast nodes for further processing.'

.. directive:: 
   {}
   A second directive to play
   with the indentation level with _italic_, **bold**, are not parsed.

_mydirective_handler(
args='',
options={}, 
value='A second directive to play\nwith the indentation level with _italic_, **bold**, are not parsed.'

Nested directives:

Various test cases

This paragraph should contain a literal with a new line here->| |<, in the final output it should render properly without the line break, but a space.

Signature gallery

In addition to example1, this module exposes a small gallery of callables covering the main kinds of Python signatures papyri has to handle:

• simple_generator, fibonacci — plain synchronous generators.

• async_fetch — an async def coroutine function.

• async_counter — an async def generator (asynchronous iterator).

• positional_only, keyword_only, mixed_signature — parameter-kind coverage (positional-only, keyword-only, all-kinds).

• higher_order — a Callable annotation.

• Patti — a class whose methods cross-link to the functions above.

Their docstrings reference each other with :func:, :meth: and :class: roles so the cross-linker has a self-contained, fully resolvable graph to exercise.

Backtick edge cases

Interpreted text with a trailing alphabetic suffix is technically invalid RST (the spec requires the end-string to be followed by non-alphanumeric characters), but it is common in scientific docstrings. The RST-correct form uses a backslash-escaped space: \`None\`\ s. Papyri applies a best-effort heuristic that splits the node into an InlineRole plus a plain Text suffix.

Examples of the pattern (rendered here so the viewer can exercise the fix):

• Returning `None`s when no data is found.

• An array of `ndarray`s stacked along axis 0.

• Pass `True`s and `False`s for boolean masks.

• Either `int`s or `float`s are accepted.