docs: Integrate user guide (pola-rs#11089)

pirr · Sep 14, 2023 · b418622 · b418622
1 parent 6886949
commit b418622
Show file tree

Hide file tree

Showing 170 changed files with 10,733 additions and 27 deletions.
diff --git a/.github/workflows/docs-global.yml b/.github/workflows/docs-global.yml
@@ -0,0 +1,85 @@
+name: Build documentation
+
+on:
+  pull_request:
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - .github/workflows/docs-global.yml
+  push:
+    tags:
+      - py-**
+
+jobs:
+  markdown-link-check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: gaurav-nelson/github-action-markdown-link-check@v1
+      with:
+        folder-path: docs
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: psf/black@stable
+        with:
+          src: docs/src/python
+          version: "23.7.0"
+
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Create virtual environment
+        run: |
+          python -m venv .venv
+          echo "$GITHUB_WORKSPACE/.venv/bin" >> $GITHUB_PATH
+
+      - name: Install dependencies
+        run: |
+          pip install -r py-polars/requirements-dev.txt
+          pip install -r docs/requirements.txt
+
+      - name: Set up Rust
+        run: rustup show
+
+      - name: Cache Rust
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: py-polars
+          save-if: ${{ github.ref_name == 'main' }}
+
+      - name: Install Polars
+        working-directory: py-polars
+        run: |
+          source activate
+          maturin develop
+
+      - name: Set up Graphviz
+        uses: ts-graphviz/setup-graphviz@v1
+
+      - name: Build documentation
+        run: mkdocs build
+
+      - name: Add .nojekyll
+        if: ${{ github.ref_type == 'tag' }}
+        working-directory: site
+        run: touch .nojekyll
+
+      - name: Deploy docs
+        if: ${{ github.ref_type == 'tag' }}
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: site
+          clean-exclude: |
+            docs/
+            py-polars/
+          single-commit: true
diff --git a/.github/workflows/test-python.yml b/.github/workflows/test-python.yml
@@ -41,6 +41,9 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
+      - name: Set up Graphviz
+        uses: ts-graphviz/setup-graphviz@v1
+
       - name: Create virtual environment
         run: |
           python -m venv .venv
@@ -65,11 +68,13 @@ jobs:
 
       - name: Run tests and report coverage
         if: github.ref_name != 'main'
-        run: pytest --cov -n auto --dist loadgroup -m "not benchmark"
+        run: pytest --cov -n auto --dist loadgroup -m "not benchmark and not docs"
 
       - name: Run doctests
         if: github.ref_name != 'main'
-        run: python tests/docs/run_doctest.py
+        run: |
+          python tests/docs/run_doctest.py
+          pytest tests/docs/test_user_guide.py -m docs
 
       - name: Check import without optional dependencies
         if: github.ref_name != 'main'
@@ -125,7 +130,7 @@ jobs:
 
       - name: Run tests
         if: github.ref_name != 'main'
-        run: pytest -n auto --dist loadgroup -m "not benchmark"
+        run: pytest -n auto --dist loadgroup -m "not benchmark and not docs"
 
       - name: Check import without optional dependencies
         if: github.ref_name != 'main'

diff --git a/.gitignore b/.gitignore
@@ -1,27 +1,37 @@
 *.iml
 *.so
 *.ipynb
-.DS_Store
 .ENV
-.coverage
 .env
-.hypothesis/
-.idea/
 .ipynb_checkpoints/
-.mypy_cache/
-.pytest_cache/
 .python-version
 .yarn/
-.vscode/
-__pycache__/
-AUTO_CHANGELOG.md
-Cargo.lock
 coverage.lcov
 coverage.xml
 data/
-node_modules/
 polars/vendor
-target/
-venv*/
-.venv*/
+
+# OS
+.DS_Store
+
+# IDE
+.idea/
+.vscode/
 .vim
+
+# Python
+.hypothesis/
+.mypy_cache/
+.pytest_cache/
+.venv/
+__pycache__/
+.coverage
+
+# Rust
+target/
+Cargo.lock
+
+# Project
+/docs/data/
+/docs/images/
+/docs/people.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -148,12 +148,12 @@ If you are stuck or unsure about your solution, feel free to open a draft pull r
 
 ## Contributing to documentation
 
-The most important components of Polars documentation are the [user guide](https://pola-rs.github.io/polars-book/user-guide/), the API references, and the database of questions on [StackOverflow](https://stackoverflow.com/).
+The most important components of Polars documentation are the [user guide](https://pola-rs.github.io/polars/user-guide/), the API references, and the database of questions on [StackOverflow](https://stackoverflow.com/).
 
 ### User guide
 
-The user guide is maintained in the [polars-book](https://github.com/pola-rs/polars-book) repository.
-For contributing to the user guide, please refer to the [contributing guide](https://github.com/pola-rs/polars-book/blob/master/CONTRIBUTING.md) in that repository.
+The user guide is maintained in the `docs` folder.
+Further contributing information will be added shortly.
 
 ### API reference
 

diff --git a/Makefile b/Makefile
@@ -20,6 +20,11 @@ requirements: .venv  ## Install/refresh Python project requirements
 	$(VENV_BIN)/pip install --upgrade -r py-polars/requirements-dev.txt
 	$(VENV_BIN)/pip install --upgrade -r py-polars/requirements-lint.txt
 	$(VENV_BIN)/pip install --upgrade -r py-polars/docs/requirements-docs.txt
+	$(VENV_BIN)/pip install --upgrade -r docs/requirements.txt
+
+.PHONY: build-python
+build-python: .venv  ## Compile and install Python Polars for development
+	@$(MAKE) -s -C py-polars build
 
 .PHONY: clean
 clean:  ## Clean up caches and build artifacts

diff --git a/README.md b/README.md
@@ -40,7 +40,7 @@
   -
   <a href="https://stackoverflow.com/questions/tagged/r-polars">R</a>
   |
-  <a href="https://pola-rs.github.io/polars-book/">User Guide</a>
+  <a href="https://pola-rs.github.io/polars/">User Guide</a>
   |
   <a href="https://discord.gg/4UfP5cfBE7">Discord</a>
 </p>
@@ -58,7 +58,7 @@ Polars is a DataFrame interface on top of an OLAP Query Engine implemented in Ru
 - Hybrid Streaming (larger than RAM datasets)
 - Rust | Python | NodeJS | R | ...
 
-To learn more, read the [User Guide](https://pola-rs.github.io/polars-book/).
+To learn more, read the [User Guide](https://pola-rs.github.io/polars/).
 
 ## Python
 

diff --git a/_typos.toml b/_typos.toml
@@ -7,6 +7,7 @@ extend-ignore-identifiers-re = [
 ba = "ba"
 Fo = "Fo"
 nd = "nd"
+ND = "ND"
 opt_nd = "opt_nd"
 ser = "ser"
 strat = "strat"

diff --git a/crates/polars/src/docs/lazy.rs b/crates/polars/src/docs/lazy.rs
@@ -106,7 +106,7 @@
 //!
 //! ## Groupby
 //!
-//! This example is from the polars [user guide](https://pola-rs.github.io/polars-book/user-guide/concepts/contexts/#group_by-aggregation).
+//! This example is from the polars [user guide](https://pola-rs.github.io/polars/user-guide/concepts/contexts/#group_by-aggregation).
 //!
 //! ```
 //! use polars::prelude::*;

diff --git a/crates/polars/src/lib.rs b/crates/polars/src/lib.rs
@@ -147,7 +147,7 @@
 //! (Note that within an expression there may be more parallelization going on).
 //!
 //! Understanding polars expressions is most important when starting with the polars library. Read more
-//! about them in the [User Guide](https://pola-rs.github.io/polars-book/user-guide/concepts/expressions).
+//! about them in the [User Guide](https://pola-rs.github.io/polars/user-guide/concepts/expressions).
 //! Though the examples given there are in python. The expressions API is almost identical and the
 //! the read should certainly be valuable to rust users as well.
 //!
@@ -397,7 +397,7 @@
 //! * `POLARS_NO_CHUNKED_JOIN` -> force rechunk before joins.
 //!
 //! ## User Guide
-//! If you want to read more, [check the User Guide](https://pola-rs.github.io/polars-book/).
+//! If you want to read more, [check the User Guide](https://pola-rs.github.io/polars/).
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![allow(ambiguous_glob_reexports)]
 pub mod docs;