docs: revamp documentation (#3076)

* found an empty file and a function missing from the TOC * found an empty file * found some functions that aren't passed through * reorganized the left-bar * style: pre-commit fixes * improved the general and API reference landing pages and added links to dask-awkward documentation * writing frequently asked questions with guidance from Plausible unique visitor and time-per-page statistics * fixed some minor issues with NumPy dispatch * updated the frequently asked questions * style: pre-commit fixes * add the ability to get stdout right in Try-It for a future version of Awkward * turn old try-it notebook into a getting-started tutorial * explicitly point out the tutorials (some people would have to click the moustache icon to see the left-bar) * brought in HSF Training tutorial * correction about ak.ravel * maybe fixes redirects * added HATS tutorial * swap the source file so that it's not too slow for GitHub Actions * added all of the tutorials; updated the page of talks * hist[plot] * and particle * and vector * and skhep_testdata * I mean, scikit-hep-testdata * update warnings about cppyy * don't imply that Awkward-JAX only works on CPUs * wrote 'Single item detail' * put the same intro text on all section starters * finished 'Simple slicing' * finished 'Checking validity' * finished 'NumPy functions' * finished 'Awkward broadcasting' * finished 'Reducing' * mention 'ak.enforce_type' * explicitly add Plausible to the try-it page because it doesn't use a template * wrote how-to-math-statistics * also remove the [todo] from TOC * wrote how-to-math-argminmax * wrote how-to-math-gpu * add previously-forgotten how-to-strings section * wrote how-to-filter-num * still working on how-to-filter-cut-mask... * wrote how-to-filter-cut-mask * removed how-to-restructure-rename-records; it's not useful * wrote how-to-restructure-concatenate * removed how-to-restructure-sort; it wouldn't be any different from the API reference * wrote how-to-combinations-cartesian-combinations * wrote how-to-combinatorics-best-match * writing how-to-use-in-numba-features and NOT DONE * a special section on ArrayBuilder in Numba won't be needed * writing how-to-use-in-numba-features and NOT DONE * writing how-to-use-in-numba-features and NOT DONE * replace absolute links with relative ones (if possible) * wrote how-to-use-in-numba-features * remove 'specialized behavior' because it's all covered in 'ak.behavior', anyway --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
scikit-hep · Apr 26, 2024 · b0c462c · b0c462c
1 parent 76cb66b
commit b0c462c
Show file tree

Hide file tree

Showing 84 changed files with 10,484 additions and 1,206 deletions.
diff --git a/docs/_static/css/awkward.css b/docs/_static/css/awkward.css
@@ -47,3 +47,7 @@ html[data-theme="dark"] .sd-card {
   margin-top: 0.15em;
   margin-bottom: 0.15em;
 }
+
+div.toctree-wrapper {
+  display: none;
+}
diff --git a/docs/_static/js/awkward.js b/docs/_static/js/awkward.js
@@ -2,4 +2,7 @@ document.addEventListener("DOMContentLoaded", function() {
     document.querySelectorAll('a[href="_static/try-it.html"]').forEach(a => {
         a.target = "_blank";
     });
+    document.querySelectorAll('a[href="https://awkward-array.org/doc/main/_static/try-it.html"]').forEach(a => {
+        a.target = "_blank";
+    });
 });
diff --git a/docs/_static/try-it.html b/docs/_static/try-it.html
@@ -2,6 +2,7 @@
 <html>
   <head>
     <meta charset="UTF-8" />
+    <script data-domain="awkward-array.org" defer="defer" src="https://views.scientific-python.org/js/plausible.js"></script>
     <script src="https://cdn.jsdelivr.net/npm/jquery"></script>
     <script src="https://cdn.jsdelivr.net/npm/[email protected]/js/jquery.terminal.min.js"></script>
     <script src="https://cdn.jsdelivr.net/npm/[email protected]/js/unix_formatting.min.js"></script>
@@ -281,6 +282,9 @@
             `
               import numpy as np
               import awkward as ak
+              if hasattr(ak._util, "STDOUT"):
+                  import sys
+                  ak._util.STDOUT.stream = sys.stdout
               example = ak.Array([
                   [{"x": 1.1, "y": [1]}, {"x": 2.2, "y": [1, 2]}, {"x": 3.3, "y": [1, 2, 3]}],
                   [],

diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -10,14 +10,15 @@ subtrees:
       - file: getting-started/index
         subtrees:
             - entries:
-#              - file: getting-started/try-awkward-array
-              - file: getting-started/community-tutorials
+              - file: getting-started/what-is-an-awkward-array
+              - file: getting-started/10-minutes-to-awkward-array
+              - file: getting-started/uproot-awkward-columnar-hats
+              - file: getting-started/jagged-ragged-awkward-arrays
+              - file: getting-started/thinking-in-arrays
               - file: getting-started/papers-and-talks
       - file: user-guide/index
         subtrees:
             - entries:
-              - file: user-guide/10-minutes-to-awkward-array
-
               - file: user-guide/how-to-convert
                 title: "Converting arrays"
                 subtrees:
@@ -65,30 +66,30 @@ subtrees:
                       - file: user-guide/how-to-examine-type
                         title: "Data type"
                       - file: user-guide/how-to-examine-single-item
-                        title: "Single item detail [todo]"
+                        title: "Single item detail"
                       - file: user-guide/how-to-examine-list-fields
                         title: "Listing fields/keys/columns"
                       - file: user-guide/how-to-examine-simple-slicing
-                        title: "Simple slicing [todo]"
+                        title: "Simple slicing"
                       - file: user-guide/how-to-examine-checking-validity
-                        title: "Checking validity [todo]"
+                        title: "Checking validity"
 
               - file: user-guide/how-to-math
                 title: "Numerical math"
                 subtrees:
                   - entries:
                       - file: user-guide/how-to-math-numpy
-                        title: "NumPy functions [todo]"
+                        title: "NumPy functions"
                       - file: user-guide/how-to-math-broadcasting
-                        title: "Awkward broadcasting [todo]"
+                        title: "Awkward broadcasting"
                       - file: user-guide/how-to-math-reducing
-                        title: "Reducing (sum/min/any/all) [todo]"
+                        title: "Reducing (sum/min/any/all)"
                       - file: user-guide/how-to-math-statistics
-                        title: "Statistics (mean/var/std) [todo]"
+                        title: "Statistics (mean/var/std)"
                       - file: user-guide/how-to-math-argminmax
-                        title: "Using argmin/argmax [todo]"
+                        title: "Min/max/sort one array by another"
                       - file: user-guide/how-to-math-gpu
-                        title: "On GPUs [todo]"
+                        title: "Awkward Arrays on GPUs"
 
               - file: user-guide/how-to-strings
                 title: "Working with strings"
@@ -106,9 +107,9 @@ subtrees:
                 subtrees:
                   - entries:
                       - file: user-guide/how-to-filter-num
-                        title: "By number of items [todo]"
+                        title: "By number of items"
                       - file: user-guide/how-to-filter-cut-mask
-                        title: "Cuts vs. masks [todo]"
+                        title: "Cuts vs. masks"
                       - file: user-guide/how-to-filter-ragged
                         title: "Using ragged arrays"
                       - file: user-guide/how-to-filter-masked
@@ -122,34 +123,30 @@ subtrees:
                         title: "Zip/unzip and project"
                       - file: user-guide/how-to-restructure-add-fields
                         title: "Adding fields to records"
-                      - file: user-guide/how-to-restructure-rename-records
-                        title: "Renaming records [todo]"
                       - file: user-guide/how-to-restructure-flatten
                         title: "Flattening for plots"
                       - file: user-guide/how-to-restructure-pad
                         title: "Padding/clipping for machine learning"
                       - file: user-guide/how-to-restructure-concatenate
-                        title: "Concatenating and interleaving [todo]"
-                      - file: user-guide/how-to-restructure-sort
-                        title: "Sorting [todo]"
+                        title: "Concatenating and interleaving"
 
               - file: user-guide/how-to-combinatorics
                 title: "Combinatorics"
                 subtrees:
                   - entries:
                       - file: user-guide/how-to-combinatorics-cartesian-combinations
-                        title: 'Cartesian and "n choose k" [todo]'
+                        title: 'Cartesian and "n choose k"'
                       - file: user-guide/how-to-combinatorics-best-match
-                        title: "Best match between collections [todo]"
+                        title: "Best match between collections"
 
               - file: user-guide/how-to-use-in-numba
                 title: "Using arrays in Numba"
                 subtrees:
                   - entries:
+                      - file: user-guide/how-to-use-in-numba-intro.md
+                        title: "Introduction"
                       - file: user-guide/how-to-use-in-numba-features
-                        title: "Supported features [todo]"
-                      - file: user-guide/how-to-use-in-numba-arraybuilder
-                        title: "Building array output [todo]"
+                        title: "Supported features"
                       - file: user-guide/how-to-use-in-numba-cuda
                         title: "Working with CUDA"
 
@@ -163,17 +160,9 @@ subtrees:
                         title: "JIT compiling operations with C++ in cppyy"
 
               - file: user-guide/how-to-specialize
-                title: "Specialized behavior"
+                title: "Special topics"
                 subtrees:
                   - entries:
-                      - file: user-guide/how-to-specialize-subclass
-                        title: "Subclassing Array/Record [todo]"
-                      - file: user-guide/how-to-specialize-override-numpy
-                        title: "Overriding NumPy functions [todo]"
-                      - file: user-guide/how-to-specialize-in-numba
-                        title: "In Numba [todo]"
-                      - file: user-guide/how-to-specialize-lorentz
-                        title: "For physics: Lorentz vectors [todo]"
                       - file: user-guide/how-to-specialize-differentiate-jax
                         title: "Differentiation using JAX"
 

diff --git a/...user-guide/10-minutes-to-awkward-array.md → ...ng-started/10-minutes-to-awkward-array.md b/...user-guide/10-minutes-to-awkward-array.md → ...ng-started/10-minutes-to-awkward-array.md
@@ -4,7 +4,7 @@ jupytext:
     extension: .md
     format_name: myst
     format_version: 0.13
-    jupytext_version: 1.14.1
+    jupytext_version: 1.16.1
 kernelspec:
   display_name: Python 3 (ipykernel)
   language: python
@@ -29,8 +29,12 @@ Our dataset is formatted as a 611 MB [Apache Parquet](https://parquet.apache.org
 Given that this file is so large, let's first look at the *metadata* with `ak.metadata_from_parquet` to see what we're working with:
 
 ```{code-cell} ipython3
-:tags: [hide-cell]
-
+---
+editable: true
+slideshow:
+  slide_type: ''
+tags: [hide-cell]
+---
 %config InteractiveShell.ast_node_interactivity = "last_expr_or_assign"
 ```
 

diff --git a/docs/getting-started/8-layer_cube.jpg b/docs/getting-started/8-layer_cube.jpg
diff --git a/docs/getting-started/awkward-motivation-venn-diagram.svg b/docs/getting-started/awkward-motivation-venn-diagram.svg
diff --git a/docs/getting-started/cartoon-cartesian.png b/docs/getting-started/cartoon-cartesian.png
@@ -0,0 +1 @@
+../../docs-img/diagrams/cartoon-cartesian.png
diff --git a/docs/getting-started/cartoon-combinations.png b/docs/getting-started/cartoon-combinations.png
@@ -0,0 +1 @@
+../../docs-img/diagrams/cartoon-combinations.png
diff --git a/docs/getting-started/community-tutorials.md b/docs/getting-started/community-tutorials.md
diff --git a/docs/getting-started/demo/example-reduction-sum.svg b/docs/getting-started/demo/example-reduction-sum.svg
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		../../docs-img/diagrams/cartoon-combinations.png