diff --git a/Readme.md b/Readme.md index fc5b687a..c4d14bdf 100644 --- a/Readme.md +++ b/Readme.md @@ -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 @@ -42,36 +42,36 @@ And this [small presentation at CZI EOSS4 meeting in early november 2021](https: Click to expand -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) @@ -79,12 +79,12 @@ papyri enabled (left) and disabled (right). ## 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 @@ -96,43 +96,43 @@ 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. @@ -140,18 +140,17 @@ Note that papyri still uses a custom parser which will be removed in the future 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 @@ -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 ` @@ -186,42 +184,40 @@ $ papyri gen examples/scipy.toml This will create intermediate docs files in in `~/.papyri/data/_` -### 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/ ``` -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 @@ -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 @@ -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 # try to render in the terminal. ``` +For example, + +``` +$ papyri ascii numpy.linspace +``` + The next step uses urwid to provide a browsable interface in terminal. ``` @@ -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.