docs: Minor improvements to the docs website (#12084)

pola-rs · Oct 29, 2023 · eec4867 · eec4867
1 parent 4c6cc4c
commit eec4867
Show file tree

Hide file tree

Showing 8 changed files with 54 additions and 43 deletions.
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -0,0 +1,19 @@
+---
+hide:
+  - navigation
+---
+
+# API reference
+
+The API reference contains detailed descriptions of all public functions and objects.
+It's the best place to look if you need information on a specific function.
+
+## Python
+
+The Python API reference is built using Sphinx.
+It's available on [GitHub Pages](https://pola-rs.github.io/polars/py-polars/html/reference/index.html).
+
+## Rust
+
+The Rust API reference is built using Cargo.
+It's available on [docs.rs](https://docs.rs/polars/latest/polars/).
diff --git a/docs/index.md b/docs/index.md
@@ -34,27 +34,27 @@ Polars is a highly performant DataFrame library for manipulating structured data
 
 ## About this guide
 
-The `Polars` user guide is intended to live alongside the API documentation. Its purpose is to explain (new) users how to use `Polars` and to provide meaningful examples. The guide is split into two parts:
+The Polars user guide is intended to live alongside the API documentation. Its purpose is to explain (new) users how to use `Polars` and to provide meaningful examples. The guide is split into two parts:
 
-- [Getting Started](getting-started/intro.md): A 10 minute helicopter view of the library and its primary function.
-- [User Guide](user-guide/index.md): A detailed explanation of how the library is setup and how to use it most effectively.
+- [Getting started](getting-started/intro.md): A 10 minute helicopter view of the library and its primary function.
+- [User guide](user-guide/index.md): A detailed explanation of how the library is setup and how to use it most effectively.
 
 If you are looking for details on a specific level / object, it is probably best to go the API documentation: [Python](https://pola-rs.github.io/polars/py-polars/html/reference/index.html) | [Rust](https://docs.rs/polars/latest/polars/).
 
 ## Performance :rocket: :rocket:
 
-`Polars` is very fast, and in fact is one of the best performing solutions available.
+Polars is very fast, and in fact is one of the best performing solutions available.
 See the results in h2oai's [db-benchmark](https://duckdblabs.github.io/db-benchmark/), revived by the DuckDB project.
 
-`Polars` [TPCH Benchmark results](https://www.pola.rs/benchmarks.html) are now available on the official website.
+Polars [TPC-H Benchmark results](https://www.pola.rs/benchmarks.html) are now available on the official website.
 
 ## Example
 
 {{code_block('home/example','example',['scan_csv','filter','group_by','collect'])}}
 
 ## Community
 
-`Polars` has a very active community with frequent releases (approximately weekly). Below are some of the top contributors to the project:
+Polars has a very active community with frequent releases (approximately weekly). Below are some of the top contributors to the project:
 
 --8<-- "docs/people.md"
 
@@ -64,4 +64,4 @@ We appreciate all contributions, from reporting bugs to implementing new feature
 
 ## License
 
-This project is licensed under the terms of the MIT license.
+This project is licensed under the terms of the [MIT license](https://github.com/pola-rs/polars/blob/main/LICENSE).
diff --git a/docs/releases/changelog.md b/docs/releases/changelog.md
@@ -1,4 +1,5 @@
 # Changelog
 
-This page is under construction.
-Please refer to our [GitHub releases](https://github.com/pola-rs/polars/releases) in the meantime.
+Polars uses GitHub to manage both Python and Rust releases.
+
+Refer to our [GitHub releases page](https://github.com/pola-rs/polars/releases) for the changelog associated with each new release.
diff --git a/docs/releases/upgrade/0.19.md b/docs/releases/upgrade/0.19.md
@@ -1,13 +1,7 @@
-# 0.19
-
-This document is intended to help you upgrade from an older Polars version to Polars version `0.19.*`.
-
-For the full list of changes, please see the [release notes](https://github.com/pola-rs/polars/releases/tag/py-0.19.0).
+# Version 0.19
 
 ## Breaking changes
 
-While this section does not contain an exhaustive list of all breaking changes, we think these are most likely to impact your code.
-
 ### Aggregation functions no longer support horizontal computation
 
 This impacts aggregation functions like `sum`, `min`, and `max`.
@@ -16,7 +10,7 @@ Recently, new dedicated functionality for horizontal computation was released, a
 
 Restore the old behavior by using the horizontal variant, e.g. `sum_horizontal`.
 
-#### Example
+**Example**
 
 Before:
 
@@ -58,7 +52,7 @@ Also fixed an issue when setting this parameter to `False` would erroneously res
 
 To restore the old behavior, set `ignore_nulls` to `False` and check for `None` output.
 
-#### Example
+**Example**
 
 Before:
 
@@ -82,7 +76,7 @@ Most notably, many `ValueError`s were changed to `TypeError`s.
 
 If your code relies on handling Polars exceptions, you may have to make some adjustments.
 
-#### Example
+**Example**
 
 Before:
 
@@ -106,7 +100,7 @@ Methods like `select` and `with_columns` accept one or more expressions.
 But they also accept strings, integers, lists, and other inputs that we try to interpret as expressions.
 We updated our internal logic to parse inputs more consistently.
 
-#### Example
+**Example**
 
 Before:
 
@@ -143,7 +137,7 @@ shape: (2, 2)
 If you used the built-in Python `random.seed` function to control the randomness of Polars expressions, this will no longer work.
 Instead, use the new `set_random_seed` function.
 
-#### Example
+**Example**
 
 Before:
 
@@ -195,5 +189,5 @@ We now consolidate all our functionality for user-defined functions under the na
 | `Series/Expr.rolling_apply` | `rolling_map`  |
 | `DataFrame.apply`           | `map_rows`     |
 | `GroupBy.apply`             | `map_groups`   |
-| `pl.apply`                  | `map_groups`   |
+| `apply`                     | `map_groups`   |
 | `map`                       | `map_batches`  |
diff --git a/docs/releases/upgrade/index.md b/docs/releases/upgrade/index.md
@@ -0,0 +1,13 @@
+# About
+
+Polars releases an upgrade guide alongside each breaking release.
+This guide is intended to help you upgrade from an older Polars version to the new version.
+
+Each guide contains all breaking changes that were not previously deprecated, as well as any significant new deprecations.
+
+A full list of all changes is available in the [changelog](../changelog.md).
+
+!!! rust "Note"
+
+    There is no upgrade guide yet for Rust releases.
+    It will be added once the rate of breaking changes to the rust API slows down and a [deprecation policy](../../development/versioning.md#deprecation-period) is added.
diff --git a/docs/user-guide/misc/contributing.md b/docs/user-guide/misc/contributing.md
diff --git a/docs/user-guide/misc/reference-guides.md b/docs/user-guide/misc/reference-guides.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1,7 +1,7 @@
 # https://www.mkdocs.org/user-guide/configuration/
 
 # Project information
-site_name: Polars documentation
+site_name: Polars
 site_url: https://pola-rs.github.io/polars
 repo_url: https://github.com/pola-rs/polars
 repo_name: pola-rs/polars
@@ -82,16 +82,17 @@ nav:
     - Misc:
       - user-guide/misc/multiprocessing.md
       - user-guide/misc/alternatives.md
-      - user-guide/misc/reference-guides.md
-      - user-guide/misc/contributing.md
+
+  - API reference: api/index.md
 
   - Development:
     - development/contributing.md
     - development/versioning.md
 
   - Releases:
     - releases/changelog.md
-    - Upgrade guide:
+    - Upgrade guides:
+      - releases/upgrade/index.md
       - releases/upgrade/0.19.md
 
 not_in_nav: |