search

pola-rs / polars

Dataframes powered by a multithreaded, vectorized query engine, written in Rust
https://docs.pola.rs
Other
29.36k stars 1.86k forks source link

Intra-doc links in the Python API documentation #14145

Open BGR360 opened 7 months ago

BGR360 commented 7 months ago

Description

It'd be great if the Python API docs had more intra-doc links to make navigation easier, like the Rust docs have.

Example: the class listing for BatchedCSVReader directs the reader to pl.read_csv_batched but they cannot click on it:

image

Likewise, the page for pl.read_csv_batched does not link back to BatchedCSVReader or its next method:

image

Is there any existing philosophy for intra-doc links in the Python API docs?

Also, what docs generator is used for the Python API docs? I'm curious to read its documentation and learn its capabilities.

Link

https://docs.pola.rs/py-polars/html/reference/api/polars.read_csv_batched.html

cmdlineluser commented 7 months ago

what docs generator is used for the Python API docs?

https://docs.pola.rs/development/contributing/#python - "Polars uses Sphinx to build the API reference."

I think the "sphinx directory" is: https://github.com/pola-rs/polars/tree/main/py-polars/docs/source

BGR360 commented 7 months ago

Another thing that would be great is if parameters and return types in method signatures had hyperlinks too. I'll try to see if sphinx supports that.

image

The primitive types have hyperlinks but BatchedCSVReader does not.

Wainberg commented 7 months ago

I added a bunch of intradoc links in this PR: https://github.com/pola-rs/polars/pull/13402, but the core developers wanted it split into bite-sized chunks so it would be easier to review. Should hopefully be integrated eventually.