Skip to content

Commit

Permalink
Readme improvements (#310)
Browse files Browse the repository at this point in the history 
Small typos and grammar fixes to Readme. Also updates dev installation
instructions.
  • Loading branch information
@Carreau
Carreau authored Oct 30, 2023
2 parents 605e3da + d9721b4 commit 1f193f8
Showing 1 changed file with 61 additions and 61 deletions.
122 changes: 61 additions & 61 deletions Readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,16 +22,16 @@ Papyri allows:

See some of the reasons behind the project on [this blog post](https://labs.quansight.org/blog/2021/05/rethinking-jupyter-documentation/).

Key motivation is building a set of tools to build better documentation for Python project.
- Uses an opinionated implementation to enable better understanding more about the structure of your project.
- Allow automatic cross link (back and forth) between documentation across python packages.
- Use a documentation IR (intermediate representation), to separate building the docs from rendering the docs in many contexts.
Key motivation is building a set of tools to build better documentation for Python projects.
- Uses an opinionated implementation to enable better understanding about the structure of your project.
- Allow automatic cross-links (back and forth) between documentation across Python packages.
- Use a documentation IR (intermediate representation) to separate building the docs from rendering the docs in many contexts.

This approach should hopefully allow a conda-forge-like model, where projects upload their IR to a given repo, a _single
website_ that contains multiple project documentation (without sub domains) can be buildt with better cross links between
website_ that contains documentation for multiple projects (without sub domains). The documentation pages can then be built with better cross-links between
projects, and _efficient_ page rebuild.

This should also allow displaying reader documentation on _non html_ backend (think terminal), or provide documentation in an
This should also allow displaying user-facing documentation on _non html_ backends (think terminal), or provide documentation in an
IDE (Spyder/Jupyterlab), without having to iframe it.

## Overview Presentation
Expand All @@ -42,49 +42,49 @@ And this [small presentation at CZI EOSS4 meeting in early november 2021](https:

<detail>
<summary>Click to expand</summary>
Navigating astropy's documentation from within IPython, note that this include
forward ref but also backward reference (which pages link to current page)
Navigating astropy's documentation from within IPython. Note that this includes
forward refs but also backward references (i.e. which pages link to the current page.)

![](assets/astropy.gif)

Type inference and keyboard navigation in terminal: Directive are properly
Type inference and keyboard navigation in terminal: Directives are properly
rendered in terminal, examples are type inferred, clicking (or pressing enter)
on highlighted token would open said page (backspace navigate back).
on highlighted tokens would open said page (backspace navigates back).

![](assets/papyri-nav.gif)

Jupyter Notebook and Lab pager can render HTML it should be possible to have
inline graph and images when using jupyter inline help (to be implemented), in
terminals we replace inline images with a button/link to open images in an
Since Jupyter Notebook and Lab pages can render HTML, it should be possible to have
inline graphs and images when using Jupyter inline help (to be implemented). In
terminals, we replace inline images with a button/link to open images in an
external viewer (quicklook, evince, paint...)

![](assets/inline_graph.png)

Papyri has complete information about which page link to which page; this allows
to create local graph of which page mention each other to find related topics.
Papyri has complete information about which pages link to other pages; this allows
us to create a local graph of which pages mention each other to find related topics.

Local connectivity graph for `numpy.zeros` (d3js, draggable, clickable),
numpy.zeroes links to (or is linked from) by all dots present there. Green other
numpy functions; Blue skimage functions, orange: scipy, red: xarray. Arrow
between dots indicate those pages link each other (for example ndarray is linked
from xarray.cos), and dot size represent the popularity of a page.
Below, you can see the local connectivity graph for `numpy.zeros` (d3js, draggable, clickable).
`numpy.zeroes` links to (or is linked from) all dots present there. In green, we show other
numpy functions; in blue, we show skimage functions; in orange, we show scipy functions; in red, we show xarray functions. Arrows
between dots indicate pages which link to each other (for example ndarray is linked
from `xarray.cos`), and dot size represents the _popularity_ of a page.

![](assets/local_graph_zeroes.png)

Math are properly rendered even in terminal, here `polyfit` in IPyhton with
Math expressions are properly rendered even in the terminal: here, `polyfit` is shown in IPyhton with
papyri enabled (left) and disabled (right).

![](assets/vs_math.png)
</detail>

## Installation (not fully functional):

Some functionality are not yet available when installing from PyPI,
Some functionality is not yet available when installing from PyPI.
For now you need a dev-install (see next section) to access all features.

You'll need Python 3.8 or newer, otherwise pip will tell you it can't find any matching distribution.

Pip install from Pypi:
Pip install from PyPI:

```bash
$ pip install papyri
Expand All @@ -96,62 +96,61 @@ Install given package documentation:
$ papyri install package_name [package_name [package_name [...]]]
```
Only numpy 1.20.0, scipy 1.5.0 , xarray 0.17.0, are currently installable and published.
Only numpy 1.20.0, scipy 1.5.0 and xarray 0.17.0 are currently installable and published.
For other packages you will need to build locally which is a much more involved
process.
Run terminal IPython with Papyri as an extension:
Run IPython terminal with Papyri as an extension:
```
$ ipython --ext papyri.ipython
```
This will augment the `?` operator to show better documentation (when install with `papyri install ...`
This will augment the `?` operator to show better documentation (when installed with `papyri install ...`
*Papyri does not completely build it's own docs yet but you might be able to view a static rending of it
*Papyri does not completely build its own docs yet, but you might be able to view a static rendering of it
[here](https://pydocs.github.io/). It is not yet automatically built, so might be out of date.*
### Development install
You may need to get a modified version of numpydoc depending on the stage of development. You will need [pip >
21.3](https://pip.pypa.io/en/stable/news/#v21-3-1) if you want to make editable installs
21.3](https://pip.pypa.io/en/stable/news/#v21-3-1) if you want to make editable installs.
```
# clone this repo
# cd this repo
pip install -e .
pip install -e .
```
Build the TreeSitter rst parser:
Some functionality require ``tree_sitter_rst``.
Some functionality requires ``tree_sitter_rst``. To build the TreeSitter rst parser:
```bash
$ git clone https://github.com/stsewd/tree-sitter-rst
$ cd tree-sitter-rst
$ git checkout 3fc88d2097bc854ab6bf70c52b3c482849cf8e8f
$ cd -
$ papyri build-parser
```
Look at CI file if those instructions are not up to date.
[Look at CI file](https://github.com/jupyter/papyri/blob/main/.github/workflows/python-package.yml) if those instructions are not up to date.
Note that papyri still uses a custom parser which will be removed in the future to rely mostly on TreeSitter.
## Usage
In the end there should be roughly 3 steps,
- IR generation (package maintainers).
- IR generation (package maintainers)
- IR installation (end user or via pip/conda)
- IR Rendering (usually IDE, Cli/webserver)
- IR rendering (usually IDE, CLI/webserver)
### IR Generation
This is the step you want to trigger if you are building documentation using Papyri for a library you maintain. Most
likely as an end user you will not have to issue this step and can install pre-published documentation bundles.
This step is likely to occurs only once per new release of a project.
Look at the Toml files in `examples`, this give you example configuration from some existing libraries.
This step is likely to occur only once per new release of a project.
Look at the Toml files in `examples`, this will give you example configurations from some existing libraries.
```
$ ls -1 examples/*.toml
Expand All @@ -167,8 +166,7 @@ examples/skimage.toml
Right now these files lives in papyri but would likely be in relevant repositories under `docs/papyri.toml` later on.
It is _slow_ on full numpy/scipy, use `--no-infer` see below for a subpar but
It is _slow_ on full numpy/scipy; use `--no-infer` (see below) for a subpar but
faster experience.
Use `papyri gen <path to example file>`
Expand All @@ -186,42 +184,40 @@ $ papyri gen examples/scipy.toml
This will create intermediate docs files in in `~/.papyri/data/<library name>_<library_version>`
### installation/ingestion
### Installation/ingestion
The installation/ingestion of documentation bundles is the step that makes all
bundles "aware" of each other, and allow crosslinking/indexing to work.
bundles "aware" of each other, and allows crosslinking/indexing to work.
We ll reserve the term "install" and "installation" when you download pre-build
We'll reserve the term "install" and "installation" for when you download pre-build
documentation bundle from an external source and give only the package name
– which is not completely implemented yet.
– which is not completely implemented yet.
You can ingest local folders with the following command:
```
$ papyri ingest ~/.papyri/data/<path to folder generated at previous step>
```
This will crosslink the newly generate folder will the existing ones.
This will crosslink the newly generate folder with the existing ones.
Ingested data can be found in `~/.papyri/ingest/` but you are not supposed to
interact with this folder with tools external to papyri.
There is currently a couple of pre-built documentation bundle that can be
pre-installed, but are likely to break with each new version of papyri, we
suggest for you to use the developer install and ingestion procedure for now.
There is currently a couple of pre-built documentation bundles that can be
pre-installed, but are likely to break with each new version of papyri. We
suggest you use the developer installation and ingestion procedure for now.
## Rendering
The last step of the papyri pipeline is to render the docs, or the subset that
is of interest to you. This will likely be done by your favorite IDE, probably
just in time when you explore documentation for you. Nonetheless we've
implemented a couple of external render to help debug issues.
just in time when you explore documentation. Nonetheless, we've
implemented a couple of external renderers to help debug issues.
WARNING:
Many render methods current require papyri own docs to be build and ingested
first.
Many rendering methods current require papyri's own docs to be built and ingested
first.
```
$ papyri gen examples/papyri.toml
Expand All @@ -234,8 +230,7 @@ Or you can try to pre-install an old papyri doc bundle
$ papyri install papyri
```
### Standalone Html rendering
### Standalone HTML rendering
```bash
Expand All @@ -244,17 +239,22 @@ $ papyri serve-static # start a http.server with the propoer root to serve above
```
```bash
$ papyri serve # start a server that will render the pages on the fly (nice to debug or iterate on theme, rendering)
$ papyri serve # start a server that will render the pages on the fly (nice to debug or iterate on theme, rendering)
```
### Ascii terminal rendering
### Ascii terminal rendering (experimental)
```
$ papyri ascii <fully qualified names> # try to render in the terminal.
```
For example,
```
$ papyri ascii numpy.linspace
```
The next step uses urwid to provide a browsable interface in terminal.
```
Expand All @@ -266,7 +266,7 @@ inference of examples. `--exec` option need to be passed to try to execute examp
## Papyri - Name's meaning
See the legendary [Villa of Papyri](https://en.wikipedia.org/wiki/Villa_of_the_Papyri), who get its name from it's
See the legendary [Villa of Papyri](https://en.wikipedia.org/wiki/Villa_of_the_Papyri), which get its name from its
collection of many papyrus scrolls.
Expand Down

0 comments on commit 1f193f8

Please sign in to comment.