To remove in the future –– papyri
Papyri – in progress
Here are a couple of documents, or docstrings that are of interest to see how papyri works, generally because they crashed papyri at some point during the development, and/or do not work yet. You likely want to see the readme.md file for now which is kept up do date more often.
pip install papyri
You may need to get a modified version of numpydoc depending on the stage of development.
git clone https://github.com/jupyter/papyri cd papyri pip install -e .
Build the TreeSitter rst parser:
Some functionality require tree_sitter_rst
, see run papyri build-parser
, and CI config file on how to build the tree-sitter shared object locally:
git clone https://github.com/stsewd/tree-sitter-rst papyri build-parser
There are mostly 3 stages to run papyri, so far you need to do the 3 steps/roles on your local machine, but it will not be necessary once papyri is production ready. The three stages are:
As a library maintainer, generate and publish papyri IRD file.
As a system operator, install IRD files on your system
As a user, view the documentation in your IDE, webbrowser... with your preferences.
To generate IRD files:
$ papyri gen <config file>
You can look in the examples
folder to see some of these config files. Those will put IRD files in ~/.papyri/data
there is no upload mechanism yet.
To install those files:
$ papyri ingest ~/.papyri/data/library_version/
And finally to view the docs, either follow your IED documentation or use some of the built-in renderer:
$ papyri render $ papyri browse .... $ papyri serve
Here are a couple of function that are of interest to explore what papyri can do and render.
one of the parameter of the docstring has multiple paragraphs.
Block Verbatim in params ?
contain a DefListItem
parsing of example is completely incorrect.
misparse example as well.
item list
custom double dot example
unnumbered list with indent.
contain a reference via .. _palettable: value
and autolink paletable_
.
hase warning sections.
contains multiple figure
multiple figures
The Parameter section have a pair of parameter separated with the coma in the name field; and those parameter should be properly detected as local references in the rest of the docstrings.
should have plenty of math items
The see also section links to scipy.interpolate.UnivariateSpline
which will not resolve (yet) as the fully qualified name is scipy.interpolate.fitpack2.UnivariateSpline
; this should be fixed at some points via aliases; in the intro one link as a name <value>
syntax which is also not yet recognized.
multi blocks in enumerated list
blockquote insted of enumerate list (to fix upstream)
has lineblocks, which I belive is wrong.
multiple figures
one of the longest numpy docstring/document, or at least one of the longest to render, with scipy.signal.windows.windows.dpss
, scipy.optimize._minimize.minimize
and scipy.optimize._basinhopping.basinhopping
Papyri parsing might be a bit different from docutils/sphinx parsing. As docutils try to keep backward compatibility for historical reason, we may be a bit stricter on some of the syntax you use to. This allows us to catch more errors. Feel free to report differences in parsing, here we document the one we do on purpose.
Directive must not have spaces before double colon:
.. directive :: will be seen as a comment.
and thus this will not appear in final output.
.. directive:: is the proper way to write block directive.
it will be properly interpreted.
Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.
Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)
SVG is more flexible but power hungry; and does not scale well to 50 + nodes.
All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them