pola-rs / polars

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

Sphinx documentation does not include cross-references to some classes #7027

Open hexane360 opened 1 year ago

hexane360 commented 1 year ago

Polars version checks

Issue description

I am trying to write documentation which references polars data types (py:class:polars.DataFrame, py:class:polars.Series, and py:class:polars.Expr). However, references to these aren't currently exported in polars' objects.inv (at https://pola-rs.github.io/polars/py-polars/html/objects.inv). Would it be possible to add references to these for use by downstream libraries?

Reproducible example

$ wget https://pola-rs.github.io/polars/py-polars/html/objects.inv
$ python -m sphinx.ext.intersphinx objects.inv | egrep 'polars\.DataFrame(?:\s)'
$ python -m sphinx.ext.intersphinx objects.inv | egrep 'polars\.Series(?:\s)'

Expected behavior

$ wget https://pola-rs.github.io/polars/py-polars/html/objects.inv $ python -m sphinx.ext.intersphinx objects.inv | egrep 'polars.DataFrame(?:\s)' polars.DataFrame reference/dataframe/index.html $ python -m sphinx.ext.intersphinx objects.inv | egrep 'polars.Series(?:\s)' polars.Series reference/series/index.html

Installed versions

``` ---Version info--- Polars: 0.15.17 Index type: UInt32 Platform: macOS-13.1-arm64-arm-64bit Python: 3.10.10 (main, Feb 13 2023, 02:52:07) [Clang 14.0.0 (clang-1400.0.29.202)] ---Optional dependencies--- pyarrow: 9.0.0 pandas: 1.4.3 numpy: 1.24.1 fsspec: connectorx: xlsx2csv: deltalake: matplotlib: 3.7.0 ```
ritchie46 commented 1 year ago

Interested in opening a PR to fix those?

hexane360 commented 1 year ago

I could give it a shot, but it would take a couple days to get around to. With sphinx, it's either a really simple fix or a PITA...

danking commented 3 weeks ago

I just ran into this today. I think Polars is explicitly disabling cross-referencing on DataFrame because it is listed as :noindex:. There's some detail at https://github.com/sphinx-doc/sphinx/issues/7052 . I think we just want :noindexentry: instead which permits cross-referencing while still eliding the documented thing from the index.

danking commented 3 weeks ago

Sadly autodoc does not support :noindexentry: https://github.com/sphinx-doc/sphinx/issues/10222. The only way forward is for polars to not use :noindex: in its autodoc entries. This may result in duplicate entries if, for example, Polars creates multiple entries for DataFrame in its docs.