docs: Refactor docs directory hierarchy

.github/workflows/docs-global.yml

@@ -21,7 +21,7 @@ jobs:
           ref: ${{ github.event.client_payload.sha }}
       - uses: gaurav-nelson/github-action-markdown-link-check@v1
         with:
-          config-file: docs/mlc-config.json
+          config-file: docs/source/mlc-config.json
           folder-path: docs
 
   lint:
@@ -39,13 +39,13 @@ jobs:
 
       - uses: chartboost/ruff-action@v1
         with:
-          src: docs/
+          src: docs/source/
           version: ${{ steps.version.outputs.version }}
           args: check --no-fix
 
       - uses: chartboost/ruff-action@v1
         with:
-          src: docs/
+          src: docs/source/
           version: ${{ steps.version.outputs.version }}
           args: format --diff
 
@@ -69,7 +69,7 @@ jobs:
           echo "VIRTUAL_ENV=$GITHUB_WORKSPACE/.venv" >> $GITHUB_ENV
 
       - name: Install Python dependencies
-        run: uv pip install -r py-polars/requirements-dev.txt -r docs/requirements.txt
+        run: uv pip install -r py-polars/requirements-dev.txt -r docs/source/requirements.txt
 
       - name: Set up Rust
         run: rustup show

.github/workflows/lint-rust.yml

@@ -4,7 +4,7 @@ on:
   pull_request:
     paths:
       - crates/**
-      - docs/src/rust/**
+      - docs/source/src/rust/**
       - examples/**
       - py-polars/src/**
       - py-polars/Cargo.toml
@@ -15,7 +15,7 @@ on:
       - main
     paths:
       - crates/**
-      - docs/src/rust/**
+      - docs/source/src/rust/**
       - examples/**
       - py-polars/src/**
       - py-polars/Cargo.toml

.github/workflows/test-python.yml

@@ -5,7 +5,7 @@ on:
     paths:
       - Cargo.lock
       - py-polars/**
-      - docs/src/python/**
+      - docs/source/src/python/**
       - crates/**
       - .github/workflows/test-python.yml
   push:
@@ -14,7 +14,7 @@ on:
     paths:
       - Cargo.lock
       - crates/**
-      - docs/src/python/**
+      - docs/source/src/python/**
       - py-polars/**
       - .github/workflows/test-python.yml
 

.gitignore

@@ -39,6 +39,5 @@ target/
 *.tbl
 
 # Project
-/docs/data/
-/docs/images/
-/docs/people.md
+/docs/assets/data/
+/docs/assets/people.md

Cargo.toml

@@ -2,7 +2,7 @@
 resolver = "2"
 members = [
   "crates/*",
-  "docs/src/rust",
+  "docs/source/src/rust",
   # "examples/*",
   "py-polars",
 ]

Makefile

@@ -25,7 +25,7 @@ requirements: .venv  ## Install/refresh Python project requirements
 	   -r py-polars/requirements-dev.txt \
 	   -r py-polars/requirements-lint.txt \
 	   -r py-polars/docs/requirements-docs.txt \
-	   -r docs/requirements.txt
+	   -r docs/source/requirements.txt
 
 .PHONY: requirements-all
 requirements-all: .venv  ## Install/refresh all Python requirements (including those needed for CI tests)

README.md

@@ -102,7 +102,7 @@ shape: (5, 8)
 ## SQL
 
 ```python
->>> df = pl.scan_csv("docs/data/iris.csv")
+>>> df = pl.scan_csv("docs/assets/data/iris.csv")
 >>> ## OPTION 1
 >>> # run SQL queries on frame-level
 >>> df.sql("""
@@ -141,14 +141,14 @@ SQL commands can also be run directly from your terminal using the Polars CLI:
 
 ```bash
 # run an inline SQL query
-> polars -c "SELECT species, AVG(sepal_length) AS avg_sepal_length, AVG(sepal_width) AS avg_sepal_width FROM read_csv('docs/data/iris.csv') GROUP BY species;"
+> polars -c "SELECT species, AVG(sepal_length) AS avg_sepal_length, AVG(sepal_width) AS avg_sepal_width FROM read_csv('docs/assets/data/iris.csv') GROUP BY species;"
 
 # run interactively
 > polars
 Polars CLI v0.3.0
 Type .help for help.
 
-> SELECT species, AVG(sepal_length) AS avg_sepal_length, AVG(sepal_width) AS avg_sepal_width FROM read_csv('docs/data/iris.csv') GROUP BY species;
+> SELECT species, AVG(sepal_length) AS avg_sepal_length, AVG(sepal_width) AS avg_sepal_width FROM read_csv('docs/assets/data/iris.csv') GROUP BY species;
 ```
 
 Refer to the [Polars CLI repository](https://github.com/pola-rs/polars-cli) for more information.

crates/polars/tests/it/io/parquet/arrow/read.rs

@@ -10,7 +10,7 @@ fn all_types() -> PolarsResult<()> {
     use crate::io::parquet::read::file::FileReader;
 
     let dir = env!("CARGO_MANIFEST_DIR");
-    let path = PathBuf::from(dir).join("../../docs/data/alltypes_plain.parquet");
+    let path = PathBuf::from(dir).join("../../docs/assets/data/alltypes_plain.parquet");
 
     let mut reader = std::fs::File::open(path)?;
 
@@ -55,7 +55,7 @@ fn all_types_chunked() -> PolarsResult<()> {
 
     use crate::io::parquet::read::file::FileReader;
     let dir = env!("CARGO_MANIFEST_DIR");
-    let path = PathBuf::from(dir).join("../../docs/data/alltypes_plain.parquet");
+    let path = PathBuf::from(dir).join("../../docs/assets/data/alltypes_plain.parquet");
     let mut reader = std::fs::File::open(path)?;
 
     let metadata = read_metadata(&mut reader)?;

crates/polars/tests/it/io/parquet/read/mod.rs

@@ -34,7 +34,7 @@ pub fn hybrid_rle_iter(d: HybridRleDecoder) -> ParquetResult<std::vec::IntoIter<
 
 pub fn get_path() -> PathBuf {
     let dir = env!("CARGO_MANIFEST_DIR");
-    PathBuf::from(dir).join("../../docs/data")
+    PathBuf::from(dir).join("../../docs/assets/data")
 }
 
 /// Reads a page into an [`Array`].

docs/assets/images/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

docs/_build/scripts/macro.py → docs/source/_build/scripts/macro.py

@@ -22,7 +22,7 @@
 )
 
 # Load all links to reference docs
-with open("docs/_build/API_REFERENCE_LINKS.yml", "r") as f:
+with open("docs/source/_build/API_REFERENCE_LINKS.yml", "r") as f:
     API_REFERENCE_LINKS = yaml.load(f, Loader=yaml.CLoader)
 
 
@@ -39,7 +39,7 @@ def create_feature_flag_link(feature_name: str) -> str:
 
 
 def create_feature_flag_links(language: str, api_functions: List[str]) -> List[str]:
-    """Generate markdown feature flags for the code tas based on the api_functions.
+    """Generate markdown feature flags for the code tabs based on the api_functions.
         It checks for the key feature_flag in the configuration yaml for the function and if it exists print out markdown
 
     Args:
@@ -132,7 +132,9 @@ def code_tab(
 
 def define_env(env):
     @env.macro
-    def code_header(language: str, section: str = [], api_functions: List[str] = []) -> str:
+    def code_header(
+        language: str, section: str = [], api_functions: List[str] = []
+    ) -> str:
         language_info = LANGUAGES[language]
 
         language = language_info["code_name"]
@@ -142,7 +144,9 @@ def code_header(language: str, section: str = [], api_functions: List[str] = [])
 
         # Create API Links if they are defined in the YAML
         api_functions = [
-            link for f in api_functions if (link := create_api_function_link(language, f))
+            link
+            for f in api_functions
+            if (link := create_api_function_link(language, f))
         ]
         language_headers = " ·".join(api_functions + feature_flags_links)
         return f"""=== \":fontawesome-brands-{language_info['icon_name']}: {language_info['display_name']}\"
@@ -165,7 +169,7 @@ def code_block(
 
         for language, info in LANGUAGES.items():
             base_path = f"{language}/{path}{info['extension']}"
-            full_path = "docs/src/" + base_path
+            full_path = "docs/source/src/" + base_path
             # Check if file exists for the language
             if os.path.exists(full_path):
                 result.append(code_tab(base_path, section, info, api_functions))

docs/_build/scripts/people.py → docs/source/_build/scripts/people.py

@@ -8,10 +8,11 @@
 
 ICON_TEMPLATE = '<a href="{html_url}"><img alt="{login}" class="contributor_icon" src="{avatar_url}&s=40" loading="lazy" /></a>'
 
+
 def get_people_md():
     repo = g.get_repo("pola-rs/polars")
     contributors = repo.get_contributors()
-    with open("./docs/people.md", "w") as f:
+    with open("./docs/assets/people.md", "w") as f:
         for c in itertools.islice(contributors, 50):
             # We love dependabot, but he doesn't need a spot on our website
             if c.login == "dependabot[bot]":
@@ -28,11 +29,11 @@ def get_people_md():
 
 
 def on_startup(command, dirty):
-    """Mkdocs hook to autogenerate docs/people.md on startup"""
+    """Mkdocs hook to autogenerate docs/assets/people.md on startup"""
     try:
         get_people_md()
     except Exception as e:
-        msg = f"WARNING:{__file__}: Could not generate docs/people.md. Got error: {str(e)}"
+        msg = f"WARNING:{__file__}: Could not generate docs/assets/people.md. Got error: {str(e)}"
         print(msg)
 
 

docs/development/contributing/index.md → docs/source/development/contributing/index.md

@@ -211,7 +211,7 @@ The most important components of Polars documentation are the [user guide](https
 
 ### User guide
 
-The user guide is maintained in the `docs/user-guide` folder. Before creating a PR first raise an issue to discuss what you feel is missing or could be improved.
+The user guide is maintained in the `docs/source/user-guide` folder. Before creating a PR first raise an issue to discuss what you feel is missing or could be improved.
 
 #### Building and serving the user guide
 
@@ -244,15 +244,15 @@ To add a code block with code to be run in a shell with tabs for Python and Rust
 
 #### Adding a code block
 
-The snippets for Python and Rust code blocks are in the `docs/src/python/` and `docs/src/rust/` directories, respectively. To add a code snippet with Python or Rust code to a `.md` page, use the following format:
+The snippets for Python and Rust code blocks are in the `docs/source/src/python/` and `docs/source/src/rust/` directories, respectively. To add a code snippet with Python or Rust code to a `.md` page, use the following format:
 
 ```
 {{code_block('user-guide/io/cloud-storage','read_parquet',['read_parquet','read_csv'])}}
 ```
 
-- The first argument is a path to either or both files called `docs/src/python/user-guide/io/cloud-storage.py` and `docs/src/rust/user-guide/io/cloud-storage.rs`.
+- The first argument is a path to either or both files called `docs/source/src/python/user-guide/io/cloud-storage.py` and `docs/source/src/rust/user-guide/io/cloud-storage.rs`.
 - The second argument is the name given at the start and end of each snippet in the `.py` or `.rs` file
-- The third argument is a list of links to functions in the API docs. For each element of the list there must be a corresponding entry in `docs/_build/API_REFERENCE_LINKS.yml`
+- The third argument is a list of links to functions in the API docs. For each element of the list there must be a corresponding entry in `docs/source/_build/API_REFERENCE_LINKS.yml`
 
 If the corresponding `.py` and `.rs` snippet files both exist then each snippet named in the second argument to `code_block` above must exist or the build will fail. An empty snippet should be added to the `.py` or `.rs` file if the snippet is not needed.
 

docs/index.md → docs/source/index.md

@@ -57,7 +57,7 @@ A more extensive introduction can be found in the [next chapter](user-guide/gett
 
 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"
+--8<-- "docs/assets/people.md"
 
 ## Contributing
 

docs/src/python/home/example.py → docs/source/src/python/home/example.py

@@ -2,7 +2,7 @@
 import polars as pl
 
 q = (
-    pl.scan_csv("docs/data/iris.csv")
+    pl.scan_csv("docs/assets/data/iris.csv")
     .filter(pl.col("sepal_length") > 5)
     .group_by("species")
     .agg(pl.all().sum())

docs/src/python/user-guide/concepts/lazy-vs-eager.py → docs/source/src/python/user-guide/concepts/lazy-vs-eager.py

@@ -2,15 +2,15 @@
 
 # --8<-- [start:eager]
 
-df = pl.read_csv("docs/data/iris.csv")
+df = pl.read_csv("docs/assets/data/iris.csv")
 df_small = df.filter(pl.col("sepal_length") > 5)
 df_agg = df_small.group_by("species").agg(pl.col("sepal_width").mean())
 print(df_agg)
 # --8<-- [end:eager]
 
 # --8<-- [start:lazy]
 q = (
-    pl.scan_csv("docs/data/iris.csv")
+    pl.scan_csv("docs/assets/data/iris.csv")
     .filter(pl.col("sepal_length") > 5)
     .group_by("species")
     .agg(pl.col("sepal_width").mean())

docs/src/python/user-guide/concepts/streaming.py → docs/source/src/python/user-guide/concepts/streaming.py

@@ -1,10 +1,11 @@
 # --8<-- [start:import]
 import polars as pl
+
 # --8<-- [end:import]
 
 # --8<-- [start:streaming]
 q1 = (
-    pl.scan_csv("docs/data/iris.csv")
+    pl.scan_csv("docs/assets/data/iris.csv")
     .filter(pl.col("sepal_length") > 5)
     .group_by("species")
     .agg(pl.col("sepal_width").mean())
@@ -18,7 +19,7 @@
 # --8<-- [end:example]
 
 # --8<-- [start:example2]
-q2 = pl.scan_csv("docs/data/iris.csv").with_columns(
+q2 = pl.scan_csv("docs/assets/data/iris.csv").with_columns(
     pl.col("sepal_length").mean().over("species")
 )
 

docs/src/python/user-guide/getting-started/reading-writing.py → docs/source/src/python/user-guide/getting-started/reading-writing.py

@@ -19,24 +19,24 @@
 # --8<-- [end:dataframe]
 
 # --8<-- [start:csv]
-df.write_csv("docs/data/output.csv")
-df_csv = pl.read_csv("docs/data/output.csv")
+df.write_csv("docs/assets/data/output.csv")
+df_csv = pl.read_csv("docs/assets/data/output.csv")
 print(df_csv)
 # --8<-- [end:csv]
 
 # --8<-- [start:csv2]
-df_csv = pl.read_csv("docs/data/output.csv", try_parse_dates=True)
+df_csv = pl.read_csv("docs/assets/data/output.csv", try_parse_dates=True)
 print(df_csv)
 # --8<-- [end:csv2]
 
 # --8<-- [start:json]
-df.write_json("docs/data/output.json")
-df_json = pl.read_json("docs/data/output.json")
+df.write_json("docs/assets/data/output.json")
+df_json = pl.read_json("docs/assets/data/output.json")
 print(df_json)
 # --8<-- [end:json]
 
 # --8<-- [start:parquet]
-df.write_parquet("docs/data/output.parquet")
-df_parquet = pl.read_parquet("docs/data/output.parquet")
+df.write_parquet("docs/assets/data/output.parquet")
+df_parquet = pl.read_parquet("docs/assets/data/output.parquet")
 print(df_parquet)
 # --8<-- [end:parquet]

docs/src/python/user-guide/io/csv.py → docs/source/src/python/user-guide/io/csv.py

@@ -5,15 +5,15 @@
 
 """
 # --8<-- [start:read]
-df = pl.read_csv("docs/data/path.csv")
+df = pl.read_csv("docs/assets/data/path.csv")
 # --8<-- [end:read]
 """
 
 # --8<-- [start:write]
 df = pl.DataFrame({"foo": [1, 2, 3], "bar": [None, "bak", "baz"]})
-df.write_csv("docs/data/path.csv")
+df.write_csv("docs/assets/data/path.csv")
 # --8<-- [end:write]
 
 # --8<-- [start:scan]
-df = pl.scan_csv("docs/data/path.csv")
+df = pl.scan_csv("docs/assets/data/path.csv")
 # --8<-- [end:scan]

docs/src/python/user-guide/io/excel.py → docs/source/src/python/user-guide/io/excel.py

@@ -5,22 +5,22 @@
 
 """
 # --8<-- [start:read]
-df = pl.read_excel("docs/data/path.xlsx")
+df = pl.read_excel("docs/assets/data/path.xlsx")
 # --8<-- [end:read]
 
 # --8<-- [start:read_sheet_name]
-df = pl.read_excel("docs/data/path.xlsx", sheet_name="Sales")
+df = pl.read_excel("docs/assets/data/path.xlsx", sheet_name="Sales")
 # --8<-- [end:read_sheet_name]
 """
 
 # --8<-- [start:write]
 df = pl.DataFrame({"foo": [1, 2, 3], "bar": [None, "bak", "baz"]})
-df.write_excel("docs/data/path.xlsx")
+df.write_excel("docs/assets/data/path.xlsx")
 # --8<-- [end:write]
 
 """
 # --8<-- [start:write_sheet_name]
 df = pl.DataFrame({"foo": [1, 2, 3], "bar": [None, "bak", "baz"]})
-df.write_excel("docs/data/path.xlsx", worksheet="Sales")
+df.write_excel("docs/assets/data/path.xlsx", worksheet="Sales")
 # --8<-- [end:write_sheet_name]
 """