docs: Add make docs command, DataType docs/layout tweak, minor READ…

…ME updates (#15386)

Co-authored-by: Stijn de Gooijer <[email protected]>

README.md

@@ -198,27 +198,20 @@ You can also install a subset of all optional dependencies.
 pip install 'polars[numpy,pandas,pyarrow]'
 ```
 
-| Tag        | Description                                                                  |
-| ---------- | ---------------------------------------------------------------------------- |
-| **all**    | Install all optional dependencies (all of the following)                     |
-| pandas     | Install with pandas for converting data to and from pandas DataFrames/Series |
-| numpy      | Install with NumPy for converting data to and from NumPy arrays              |
-| pyarrow    | Reading data formats using PyArrow                                           |
-| fsspec     | Support for reading from remote file systems                                 |
-| connectorx | Support for reading from SQL databases                                       |
-| xlsx2csv   | Support for reading from Excel files                                         |
-| openpyxl   | Support for reading from Excel files with native types                       |
-| deltalake  | Support for reading and writing Delta Lake Tables                            |
-| pyiceberg  | Support for reading from Apache Iceberg tables                               |
-| plot       | Support for plot functions on DataFrames                                     |
-| timezone   | Timezone support, only needed if you are on Python<3.9 or Windows            |
+See the [User Guide](https://docs.pola.rs/user-guide/installation/#feature-flags) for more details on optional dependencies
+
+To see the current Polars version and a full list of its optional dependencies, run:
+
+```python
+pl.show_versions()
+```
 
 Releases happen quite often (weekly / every few days) at the moment, so updating Polars regularly to get the latest bugfixes / features might not be a bad idea.
 
 ### Rust
 
-You can take latest release from `crates.io`, or if you want to use the latest features / performance improvements
-point to the `main` branch of this repo.
+You can take latest release from `crates.io`, or if you want to use the latest features / performance
+improvements point to the `main` branch of this repo.
 
 ```toml
 polars = { git = "https://github.com/pola-rs/polars", rev = "<optional git tag>" }
@@ -251,18 +244,17 @@ Note that the Rust crate implementing the Python bindings is called `py-polars`
 Rust crate `polars` itself. However, both the Python package and the Python module are named `polars`, so you
 can `pip install polars` and `import polars`.
 
-## Use custom Rust function in Python?
+## Using custom Rust functions in Python
 
 Extending Polars with UDFs compiled in Rust is easy. We expose PyO3 extensions for `DataFrame` and `Series`
 data structures. See more in https://github.com/pola-rs/pyo3-polars.
 
 ## Going big...
 
-Do you expect more than 2^32 (~4.2 billion) rows? Compile Polars with the `bigidx` feature flag.
-
-Or for Python users, install `pip install polars-u64-idx`.
+Do you expect more than 2^32 (~4.2 billion) rows? Compile Polars with the `bigidx` feature
+flag or, for Python users, install `pip install polars-u64-idx`.
 
-Don't use this unless you hit the row boundary, as the default build of Polars is faster and consumes less memory.
+Don't use this unless you hit the row boundary as the default build of Polars is faster and consumes less memory.
 
 ## Legacy
 

py-polars/Makefile

@@ -55,7 +55,7 @@ build-release-native: .venv  ## Same as build-release, except with native CPU op
 	@$(MAKE) -s -C .. $@
 
 .PHONY: lint
-lint: .venv  ## Run lint checks
+lint: .venv  ## Run lint checks (only)
 	$(VENV_BIN)/ruff check
 	-$(VENV_BIN)/mypy
 
@@ -84,6 +84,15 @@ doctest: .venv build  ## Run doctests
 	$(VENV_BIN)/python tests/docs/run_doctest.py
 	$(VENV_BIN)/pytest tests/docs/test_user_guide.py -m docs
 
+.PHONY: docs
+docs: .venv build  ## Build Python docs (incremental)
+	@$(MAKE) -s -C docs html
+
+.PHONY: docs-clean
+docs-clean: .venv  ## Build Python docs (full rebuild)
+	@$(MAKE) -s -C docs clean
+	@$(MAKE) docs
+
 .PHONY: test-all
 test-all: .venv build  ## Run all tests
 	$(VENV_BIN)/pytest -n auto --dist loadgroup -m "slow or not slow"

py-polars/docs/source/reference/datatypes.rst

@@ -1,8 +1,10 @@
 ==========
 Data types
 ==========
-.. currentmodule:: polars
+.. currentmodule:: polars.datatypes
 
+DataType
+~~~~~~~~
 .. autosummary::
     :toctree: api/
     :nosignatures:
@@ -47,6 +49,17 @@ Nested
     List
     Struct
 
+String
+~~~~~~
+.. autosummary::
+    :toctree: api/
+    :nosignatures:
+
+    String
+    Categorical
+    Enum
+    Utf8
+
 Other
 ~~~~~
 .. autosummary::
@@ -55,10 +68,6 @@ Other
 
     Binary
     Boolean
-    Categorical
-    Enum
     Null
     Object
-    String
-    Utf8
     Unknown

py-polars/docs/source/reference/index.rst

@@ -77,6 +77,10 @@ methods. All classes and functions exposed in the ``polars.*`` namespace are pub
            :maxdepth: 2
 
            api
+
+        .. toctree::
+           :maxdepth: 1
+
            plugins