Merge branch 'rafaqz:main' into stack

Author: brendanjohnharris

.github/workflows/Documenter.yml

@@ -47,18 +47,14 @@ jobs:
         uses: julia-actions/setup-julia@v1
       - name: Pull Julia cache
         uses: julia-actions/cache@v1
-      - name: Install custom documentation dependencies
-        run: julia --project=docs -e 'using Pkg; pkg"add https://github.com/LuxDL/DocumenterVitepress.jl.git"; pkg"dev ."; Pkg.instantiate(); Pkg.precompile(); Pkg.status()'
       - name: Instantiate NPM
         run: cd docs/; npm i; cd ..
       - name: Generate logo
-        run: julia --project=docs/ --color=yes docs/logo.jl
-      - name: Build and deploy
+        run: julia --project=docs -e "using Pkg; Pkg.instantiate()"; julia --project=docs/ --color=yes docs/logo.jl
+      - uses: julia-actions/julia-docdeploy@v1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
           GKSwstype: "100" # https://discourse.julialang.org/t/generation-of-documentation-fails-qt-qpa-xcb-could-not-connect-to-display/60988
           JULIA_DEBUG: "Documenter"
           DATADEPS_ALWAYS_ACCEPT: true
-        run: |
-          julia --project=docs/ --color=yes docs/make.jl # this should ideally AUTO-DEPLOY!

.gitignore

@@ -22,4 +22,6 @@ docs/.vitepress/dist
 docs/.vitepress/cache
 docs/src/.vitepress/dist
 docs/src/.vitepress/cache
-node_modules
+node_modules
+*.png
+*.svg

Project.toml

@@ -39,7 +39,7 @@ ColorTypes = "0.11"
 Combinatorics = "1"
 ConstructionBase = "1"
 CoordinateTransformations = "0.6"
-DataAPI = "1"
+DataAPI = "1.16"
 DataFrames = "1"
 Dates = "1"
 Distributions = "0.25"

README.md

@@ -1,19 +1,19 @@
 # DimensionalData
 
-[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://rafaqz.github.io/DimensionalData.jl/)
+[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://rafaqz.github.io/DimensionalData.jl/stable)
+[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://rafaqz.github.io/DimensionalData.jl/dev)
 [![CI](https://github.com/rafaqz/DimensionalData.jl/actions/workflows/ci.yml/badge.svg)](https://github.com/rafaqz/DimensionalData.jl/actions/workflows/ci.yml)
 [![Codecov](https://codecov.io/gh/rafaqz/DimensionalData.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/rafaqz/DimensionalData.jl/tree/main)
 [![Aqua.jl Quality Assurance](https://img.shields.io/badge/Aqua.jl-%F0%9F%8C%A2-aqua.svg)](https://github.com/JuliaTesting/Aqua.jl)
 
-DimensionalData.jl provides tools and abstractions for working with datasets
-that have named dimensions, and optionally a lookup index. It provides no-cost
-abstractions for named indexing, and fast index lookups.
+<img src="https://rafaqz.github.io/DimensionalData.jl/dev/logoDD.png" align="right" style="padding-left:10px;" width="180"/>
 
-DimensionalData is a pluggable, generalised version of
-[AxisArrays.jl](https://github.com/JuliaArrays/AxisArrays.jl) with a cleaner
-syntax, and additional functionality found in NamedDims.jl. It has similar goals
-to pythons [xarray](http://xarray.pydata.org/en/stable/), and is primarily
-written for use with spatial data in [Rasters.jl](https://github.com/rafaqz/Rasters.jl).
+> [!TIP]
+> Visit the latest documentation at https://rafaqz.github.io/DimensionalData.jl/dev/
+
+DimensionalData.jl provides tools and abstractions for working with datasets that have named dimensions, and optionally a lookup index. It provides no-cost abstractions for named indexing, and fast index lookups.
+
+DimensionalData is a pluggable, generalised version of [AxisArrays.jl](https://github.com/JuliaArrays/AxisArrays.jl) with a cleaner syntax, and additional functionality found in NamedDims.jl. It has similar goals to pythons [xarray](http://xarray.pydata.org/en/stable/), and is primarily written for use with spatial data in [Rasters.jl](https://github.com/rafaqz/Rasters.jl).
 
 > [!IMPORTANT]
 > INSTALLATION
@@ -126,7 +126,7 @@ using DimensionalData.LookupArrays, DimensionalData.Dimensions
 ```
 
 > [!IMPORTANT]
-> Alternate Packages
+> Alternative Packages
 
 There are a lot of similar Julia packages in this space. AxisArrays.jl, NamedDims.jl, NamedArrays.jl are registered alternative that each cover some of the functionality provided by DimensionalData.jl. DimensionalData.jl should be able to replicate most of their syntax and functionality.
 

docs/Project.toml

@@ -1,16 +1,19 @@
 [deps]
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
-BetterFileWatching = "c9fd44ac-77b5-486c-9482-9798bd063cc6"
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
+CoordinateTransformations = "150eb455-5306-5404-9cee-2592286d6298"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 DimensionalData = "0703355e-b756-11e9-17c0-8b28908087d0"
 DiskArrays = "3c3547ce-8d99-4f5e-a174-61eb10b00ae3"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
-FileWatching = "7b1f6079-737a-58dc-b8bc-7a2ca5c1b5ee"
+Extents = "411431e0-e8b7-467b-b5e0-f676ba4f2910"
+Interfaces = "85a1e053-f937-4924-92a5-1367d23b7b87"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"

docs/logo.jl

@@ -1,21 +1,24 @@
 using Colors
 using CairoMakie
+using Random
+Random.seed!(13)
 CairoMakie.activate!()
-mkpath(joinpath(@__DIR__, "./src/public/"))
 
 rpyz = [Rect3f(Vec3f(0, j-0.8,k), Vec3f(0.1, 0.8,0.8))
     for j in 1:7 for k in 1:7]
 rmyz = [Rect3f(Vec3f(j-0.8, 0,k), Vec3f(0.8, 0.1,0.8))
     for j in 1:7 for k in 1:7]
 
 colors = ["#ff875f", "#0087d7", "#5fd7ff", "#ff5f87", "#b2b2b2", "#d75f00", "#00afaf"]
+base_points = [Point3f(i,j,0) for i in range(0.5,6.0,7) for j in range(0.5,6.0,7)]
+z = 2.0*rand(length(base_points))
 fig = Figure(; size=(500,500),
     backgroundcolor=:transparent,
     fonts = (; regular = "Barlow"))
 ax = LScene(fig[1,1]; show_axis=false)
 
 wireframe!.(ax, rpyz; color = colors[3], transparency=true) # shading=NoShading # bug!
-poly!.(ax, rmyz; color=colors[1], transparency=true, shading=NoShading)
+poly!.(ax, rmyz; color=0.85*colorant"#ff875f", transparency=true, shading=NoShading)
 
 meshscatter!(ax, [Point3f(0.1,0.1,0.8), Point3f(0.1+7,0.1,0.8),
     Point3f(0.1,0.1+7,0.8), Point3f(0.1+7,0.1+7,0.8)]; color = colors[4],
@@ -32,7 +35,10 @@ lines!(ax, [ Point3f(0.1+7,0.1,8), Point3f(0.1+7,0.1+7,8),
     ];
     color = colors[2],
     linewidth=2, transparency=true)
+meshscatter!(ax, base_points; marker=Rect3f(Vec3f(-0.5,-0.5,0), Vec3f(1,1,1)),
+    markersize = Vec3f.(0.5,0.5, z), color=z, colormap=tuple.(colors, 1), transparency=false)
 
-save(joinpath(@__DIR__, "src", "public", "logoDD.svg"), fig; pt_per_unit=0.75)
-save(joinpath(@__DIR__, "src", "public", "logoDD.png"), fig; px_per_unit=2)
-fig
+mkpath(joinpath(@__DIR__, "src", "assets"))
+save(joinpath(@__DIR__, "src", "assets", "logoDD.svg"), fig; pt_per_unit=0.75)
+save(joinpath(@__DIR__, "src", "assets", "logoDD.png"), fig; px_per_unit=2)
+save(joinpath(@__DIR__, "src", "assets", "favicon.png"), fig; px_per_unit=0.25)

docs/make.jl

@@ -1,53 +1,36 @@
-using DocumenterVitepress ## add https://github.com/LuxDL/DocumenterVitepress.jl.git
+using DocumenterVitepress
 using Documenter
 using DimensionalData
+using DimensionalData.Dimensions
+using DimensionalData.Lookups
+
+# Names are available everywhere so that [`function`](@ref) works.
+# ====================
+
+DocMeta.setdocmeta!(DimensionalData, :DocTestSetup, :(using DimensionalData, DimensionalData.Dimensions, DimensionalData.Dimensions.Lookups); recursive=true)
+
+# Build documentation.
+# ====================
 
 makedocs(; sitename="DimensionalData", authors="Rafael Schouten et al.",
-    # modules=[DimensionalData],
-    # checkdocs=:all,
-    format=DocumenterVitepress.MarkdownVitepress(),
+    modules=[DimensionalData],
+    checkdocs=:all,
+    format=DocumenterVitepress.MarkdownVitepress(
+        repo = "github.com/rafaqz/DimensionalData.jl",
+        devbranch = "main", 
+        devurl = "dev", 
+    ),
     draft=false,
     source="src", 
-    build=joinpath(@__DIR__, "build"), 
-    warnonly = true,
-)
-
-
-# We manually obtain the Documenter deploy configuration,
-# so we can use it to set Vitepress's settings.
-# TODO: make this better / encapsulate it in `makedocs`
-# so the user does not need to know!
-deploy_config = Documenter.auto_detect_deploy_system()
-deploy_decision = Documenter.deploy_folder(
-    deploy_config;
-    repo="github.com/rafaqz/DimensionalData.jl",
-    devbranch="main",
-    devurl = "dev",
-    push_preview=true,
+    build="build", 
+    # warnonly = true,
 )
 
-# VitePress relies on its config file in order to understand where files will exist.
-# We need to modify this file to reflect the correct base URL, however, Documenter
-# only knows about the base URL at the time of deployment.
-
-# So, after building the Markdown, we need to modify the config file to reflect the
-# correct base URL, and then build the VitePress site.
-folder = deploy_decision.subfolder
-println("Deploying to $folder")
-vitepress_config_file = joinpath(@__DIR__, "build", ".vitepress", "config.mts")
-config = read(vitepress_config_file, String)
-new_config = replace(config, "base: 'REPLACE_ME_WITH_DOCUMENTER_VITEPRESS_BASE_URL_WITH_TRAILING_SLASH'" => "base: '/DimensionalData.jl/$folder'")
-write(vitepress_config_file, new_config)
-
-# Build the docs using `npm` - we are assuming it's installed here!
-cd(@__DIR__) do
-    run(`npm run docs:build`)
-end
-touch(joinpath(@__DIR__, "build", ".vitepress", "dist", ".nojekyll"))
-
+# Deploy built documentation.
+# ===========================
 deploydocs(; 
     repo="github.com/rafaqz/DimensionalData.jl",
-    target="build/.vitepress/dist", # this is where Vitepress stores its output
+    target="build", # this is where Vitepress stores its output
     branch = "gh-pages",
     devbranch = "main",
     push_preview = true

docs/package-lock.json

@@ -1,8 +1,8 @@
 {
   "scripts": {
-    "docs:dev": "vitepress dev build",
-    "docs:build": "vitepress build build",
-    "docs:preview": "vitepress preview build"
+    "docs:dev": "vitepress dev build/.documenter",
+    "docs:build": "vitepress build build/.documenter",
+    "docs:preview": "vitepress preview build/.documenter"
   },
   "devDependencies": {
     "markdown-it-mathjax3": "^4.3.2",

docs/package.json

@@ -6,17 +6,17 @@ const version= '0.25.8'
 const VERSIONS: DefaultTheme.NavItemWithLink[] = [
   { text: `v${version} (current)`, link: '/' },
   { text: `Release Notes`, link: 'https://github.com/rafaqz/DimensionalData.jl/releases/' },
-  // { text: `Contributing`, link: 'https://github.com/twoslashes/twoslash/blob/main/CONTRIBUTING.md' },
 ]
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
-  base: 'REPLACE_ME_WITH_DOCUMENTER_VITEPRESS_BASE_URL_WITH_TRAILING_SLASH',
-  title: "DimensionalData",
+  base: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+  title: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
   description: "Datasets with named dimensions",
   lastUpdated: true,
   cleanUrls: true,
   ignoreDeadLinks: true,
+  outDir: 'REPLACE_ME_DOCUMENTER_VITEPRESS', // This is required for MarkdownVitepress to work correctly...
 
   markdown: {
     config(md) {
@@ -42,13 +42,12 @@ export default defineConfig({
       { text: 'Dimensions', link: '/dimensions' },
       { text: 'DimArrays', link: '/dimarrays' },
       { text: 'Selectors', link: '/selectors' },
-      { text: 'Integrations',
+      { text: 'Integrations', link: '/integrations',
         items: [
           { text: 'Plots and Makie', link: '/plots' },
           { text: 'Tables and DataFrames', link: '/tables' },
           { text: 'CUDA and GPUs', link: '/cuda' },
           { text: 'DiskArrays', link: '/diskarrays' },
-          { text: 'Ecosystem', link: '/integrations' },
           { text: 'Extending DimensionalData', link: '/extending_dd' },
         ],
       },
@@ -60,35 +59,35 @@ export default defineConfig({
 
     sidebar: [
       {
-        text: '',
+        text: 'Getting Started', link: '/basics',
         items: [
-          { text: 'Getting Started', link: '/basics' },
           { text: 'Dimensions', link: '/dimensions' },
           { text: 'Selectors', link: '/selectors' },
-          { text: 'Dimarrays', link: '/dimarrays' },
+          { text: 'DimArrays', link: '/dimarrays' },
           { text: 'DimStacks', link: '/stacks' },
           { text: 'GroupBy', link: '/groupby' },
           { text: 'Getting information', link: '/get_info' },
           { text: 'Object modification', link: '/object_modification' },
-          { text: 'Integrations',
-            items: [
-              { text: 'Plots and Makie', link: '/plots' },
-              { text: 'Tables and DataFrames', link: '/tables' },
-              { text: 'CUDA and GPUs', link: '/cuda' },
-              { text: 'DiskArrays', link: '/diskarrays' },
-              { text: 'Ecosystem', link: '/integrations' },
-              { text: 'Extending DimensionalData', link: '/extending_dd' },
-            ],
-          },
-          { text: 'API Reference', link: '/api/reference',
-            items: [
-              { text: 'Dimensions Reference', link: '/api/dimensions' },
-              { text: 'LookupArrays Reference', link: '/api/lookuparrays' },
-            ],
-          },
-        ]
-      }
+        ]},
+        { text: 'Integrations', link: '/integrations',
+          items: [
+            { text: 'Plots and Makie', link: '/plots' },
+            { text: 'Tables and DataFrames', link: '/tables' },
+            { text: 'CUDA and GPUs', link: '/cuda' },
+            { text: 'DiskArrays', link: '/diskarrays' },
+            { text: 'Extending DimensionalData', link: '/extending_dd' },
+          ],
+        },
+        { text: 'API Reference', link: '/api/reference',
+          items: [
+            { text: 'Dimensions Reference', link: '/api/dimensions' },
+            { text: 'LookupArrays Reference', link: '/api/lookuparrays' },
+          ],
+        },
     ],
+    editLink: {
+      pattern: 'https://github.com/rafaqz/DimensionalData.jl/edit/master/docs/src/:path'
+    },
 
     socialLinks: [
       { icon: 'github', link: 'https://github.com/rafaqz/DimensionalData.jl' },

docs/src/.vitepress/config.mts

@@ -74,9 +74,9 @@ https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/var
 
   --vp-home-hero-image-background-image: linear-gradient(
     -45deg,
-    #1f1b1c 5%,
-    #1c1b1b 5%,
-    #083f5f
+    #0087d7 35%,
+    #0087d7 35%,
+    #ff875f
   );
   --vp-home-hero-image-filter: blur(40px);
 }