From e720af238207cbc5b2d87071cd6695f57daa35fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20Gir=C3=A3o=20Serr=C3=A3o?= <5621605+rodrigogiraoserrao@users.noreply.github.com> Date: Mon, 16 Sep 2024 16:10:04 +0100 Subject: [PATCH 1/3] docs: Add explicit notes about dependencies required --- docs/development/contributing/index.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/development/contributing/index.md b/docs/development/contributing/index.md index 6758a6d79301..6bc694b82639 100644 --- a/docs/development/contributing/index.md +++ b/docs/development/contributing/index.md @@ -95,6 +95,10 @@ cd py-polars make test ``` +!!! note + + You need to have [CMake](https://cmake.org/) installed for `make test` to work. + This will do a number of things: - Use Python to create a virtual environment in the `.venv` folder. @@ -210,6 +214,7 @@ The user guide is maintained in the `docs/user-guide` folder. Before creating a #### Building and serving the user guide The user guide is built using [MkDocs](https://www.mkdocs.org/). You install the dependencies for building the user guide by running `make build` in the root of the repo. +Additionally, you need to make sure the [graphviz](https://graphviz.org/) `dot` binary is on your path. Activate the virtual environment and run `mkdocs serve` to build and serve the user guide, so you can view it locally and see updates as you make changes. From 1d419064f7f6c5bfaf92b49251911973b6a91a4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20Gir=C3=A3o=20Serr=C3=A3o?= <5621605+rodrigogiraoserrao@users.noreply.github.com> Date: Mon, 16 Sep 2024 16:12:06 +0100 Subject: [PATCH 2/3] docs: Fix formatting of nested lists. dprint uses two spaces when auto formatting the nested lists and the parser that MkDocs uses expects an indentation of at least 4 spaces or 1 tab (c.f. 'Indentation/tab length' at https://python-markdown.github.io/#differences), so we need to bypass dprint in order for the nested list to show properly. --- docs/development/contributing/index.md | 30 ++++++++++++++------------ 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/development/contributing/index.md b/docs/development/contributing/index.md index 6bc694b82639..efed407ba97b 100644 --- a/docs/development/contributing/index.md +++ b/docs/development/contributing/index.md @@ -180,22 +180,24 @@ Two other things to keep in mind: When you have resolved your issue, [open a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) in the Polars repository. Please adhere to the following guidelines: -- Title - - Start your pull request title with a [conventional commit](https://www.conventionalcommits.org/) tag. - This helps us add your contribution to the right section of the changelog. - We use the [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type). - Scope can be `rust` and/or `python`, depending on your contribution: this tag determines which changelog(s) will include your change. - Omit the scope if your change affects both Rust and Python. - - Use a descriptive title starting with an uppercase letter. - This text will end up in the [changelog](https://github.com/pola-rs/polars/releases), so make sure the text is meaningful to the user. - Use single backticks to annotate code snippets. - Use active language and do not end your title with punctuation. - - Example: ``fix(python): Fix `DataFrame.top_k` not handling nulls correctly`` -- Description - - In the pull request description, [link](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) to the issue you were working on. - - Add any relevant information to the description that you think may help the maintainers review your code. + +- Title: + - Start your pull request title with a [conventional commit](https://www.conventionalcommits.org/) tag. + This helps us add your contribution to the right section of the changelog. + We use the [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type). + Scope can be `rust` and/or `python`, depending on your contribution: this tag determines which changelog(s) will include your change. + Omit the scope if your change affects both Rust and Python. + - Use a descriptive title starting with an uppercase letter. + This text will end up in the [changelog](https://github.com/pola-rs/polars/releases), so make sure the text is meaningful to the user. + Use single backticks to annotate code snippets. + Use active language and do not end your title with punctuation. + - Example: ``fix(python): Fix `DataFrame.top_k` not handling nulls correctly`` +- Description: + - In the pull request description, [link](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) to the issue you were working on. + - Add any relevant information to the description that you think may help the maintainers review your code. - Make sure your branch is [rebased](https://docs.github.com/en/get-started/using-git/about-git-rebase) against the latest version of the `main` branch. - Make sure all [GitHub Actions checks](./ci.md) pass. + After you have opened your pull request, a maintainer will review it and possibly leave some comments. Once all issues are resolved, the maintainer will merge your pull request, and your work will be part of the next Polars release! From d89068bdb19c5d661cf00cf23db7dc7849d0ea60 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20Gir=C3=A3o=20Serr=C3=A3o?= <5621605+rodrigogiraoserrao@users.noreply.github.com> Date: Mon, 16 Sep 2024 16:12:39 +0100 Subject: [PATCH 3/3] docs: Add 'copy to clipboard' button to code snippets --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index a29cd1020af2..e178036c9720 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -143,6 +143,7 @@ theme: - navigation.footer - navigation.indexes - content.tabs.link + - content.code.copy icon: repo: fontawesome/brands/github