Skip to content

Commit 95ae76a

Browse files
BeforerrBeforerr
authored
docs: add documentation website (#9)
1 parent da2d8ee commit 95ae76a

File tree

11 files changed

+194
-19
lines changed

11 files changed

+194
-19
lines changed

‎.github/workflows/Doc.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- "src/**"
9+
- "docs/**"
10+
- "Project.toml"
11+
tags: ["*"]
12+
pull_request:
13+
paths:
14+
- "src/**"
15+
- "docs/**"
16+
- "Project.toml"
17+
workflow_dispatch:
18+
19+
concurrency:
20+
# Skip intermediate builds: always.
21+
# Cancel intermediate builds: only if it is a pull request build.
22+
group: ${{ github.workflow }}-${{ github.ref }}
23+
cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
24+
25+
jobs:
26+
docs:
27+
permissions:
28+
actions: write # needed to allow julia-actions/cache to proactively delete old caches that it has created
29+
contents: write
30+
pull-requests: read
31+
statuses: write
32+
runs-on: ubuntu-latest
33+
steps:
34+
- name: Build and deploy Documenter.jl docs
35+
uses: JuliaSpacePhysics/actions/DocsDocumenter@main

‎.github/workflows/DocCleanup.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Doc Preview Cleanup
2+
3+
on:
4+
pull_request:
5+
types: [closed]
6+
7+
# Ensure that only one "Doc Preview Cleanup" workflow is force pushing at a time
8+
concurrency:
9+
group: doc-preview-cleanup
10+
cancel-in-progress: false
11+
12+
jobs:
13+
doc-preview-cleanup:
14+
runs-on: ubuntu-latest
15+
permissions:
16+
contents: write
17+
steps:
18+
- name: Checkout gh-pages branch
19+
uses: actions/checkout@v4
20+
with:
21+
ref: gh-pages
22+
- name: Delete preview and history + push changes
23+
run: |
24+
if [ -d "${preview_dir}" ]; then
25+
git config user.name "Documenter.jl"
26+
git config user.email "[email protected]"
27+
git rm -rf "${preview_dir}"
28+
git commit -m "delete preview"
29+
git branch gh-pages-new "$(echo "delete history" | git commit-tree "HEAD^{tree}")"
30+
git push --force origin gh-pages-new:gh-pages
31+
fi
32+
env:
33+
preview_dir: previews/PR${{ github.event.number }}

‎.github/workflows/DocNav.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: Rebuild docs with newest navbar
2+
3+
on:
4+
# 6:07 AM UTC every Sunday -- choose an uncommon time to avoid
5+
# periods of heavy GitHub Actions usage
6+
schedule:
7+
- cron: "7 6 * * 0"
8+
# Whenever needed
9+
workflow_dispatch:
10+
11+
permissions:
12+
contents: write
13+
14+
jobs:
15+
update-navbar:
16+
runs-on: ubuntu-latest
17+
18+
steps:
19+
- name: Checkout gh-pages branch
20+
uses: actions/checkout@v4
21+
with:
22+
ref: gh-pages
23+
24+
- name: Insert navbar
25+
uses: TuringLang/actions/DocsNav@main
26+
with:
27+
doc-path: "."
28+
navbar-url: "https://raw.githubusercontent.com/JuliaSpacePhysics/actions/refs/heads/main/Navbar.html"
29+
30+
- name: Commit and push changes
31+
run: |
32+
if [[ -n $(git status -s) ]]; then
33+
git config user.name github-actions[bot]
34+
git config user.email github-actions[bot]@users.noreply.github.com
35+
git add -A
36+
git commit -m "Update navbar (automated)"
37+
git push
38+
else
39+
echo "No changes to commit"
40+
fi

‎README.md‎

Lines changed: 2 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# SpaceDataModel
22

33
[![Build Status](https://github.com/JuliaSpacePhysics/SpaceDataModel.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/JuliaSpacePhysics/SpaceDataModel.jl/actions/workflows/CI.yml?query=branch%3Amain)
4+
[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://JuliaSpacePhysics.github.io/SpaceDataModel.jl/dev/)
45
[![DOI](https://zenodo.org/badge/958430775.svg)](https://doi.org/10.5281/zenodo.15207556)
56
[![](https://img.shields.io/badge/%F0%9F%9B%A9%EF%B8%8F_tested_with-JET.jl-233f9a)](https://github.com/aviatesk/JET.jl)
67
[![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
@@ -10,12 +11,10 @@
1011

1112
SpaceDataModel.jl is a lightweight Julia package providing a flexible data model for handling space/heliospheric science data. It offers abstractions for organizing space data into hierarchical structures including projects, instruments, datasets, and data variables.
1213

13-
It is used in [SPEDAS.jl](https://github.com/Beforerr/SPEDAS.jl), [Speasy.jl](https://github.com/SciQLop/Speasy.jl), and [HAPIClient.jl](https://github.com/JuliaSpacePhysics/HAPIClient.jl).
14+
For information on using the package, see the documentation available at https://JuliaSpacePhysics.github.io/SpaceDataModel.jl/dev/.
1415

1516
## Installation
1617

17-
Using Julia's package manager:
18-
1918
```julia
2019
using Pkg
2120
Pkg.add("SpaceDataModel")
@@ -34,17 +33,3 @@ dataset = DataSet(name="Dataset Name")
3433
push!(project, instrument, dataset)
3534
push!(instrument, dataset)
3635
```
37-
38-
See [Data Model and Project Module - SPEDAS.jl](https://beforerr.github.io/SPEDAS.jl/dev/explanations/data_model/) for more details.
39-
40-
## Features
41-
42-
- Hierarchical organization of data (projects, instruments, datasets)
43-
- Pretty printing for data inspection
44-
45-
## Reference
46-
47-
- [SPASE Model](https://spase-group.org/data/model/index.html)
48-
- [HAPI Data Access Specification](https://github.com/hapi-server/data-specification)
49-
- [CommonDataModel.jl](https://github.com/JuliaGeo/CommonDataModel.jl)
50-
- [NetCDF Data Model](https://docs.unidata.ucar.edu/netcdf-c/current/netcdf_data_model.html)

‎docs/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
build/
2+
site/

‎docs/Project.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
[deps]
2+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

‎docs/make.jl‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
using Documenter
2+
using SpaceDataModel
3+
4+
DocMeta.setdocmeta!(SpaceDataModel, :DocTestSetup, :(using SpaceDataModel); recursive = true)
5+
6+
makedocs(
7+
sitename = "SpaceDataModel.jl",
8+
format = Documenter.HTML(),
9+
modules = [SpaceDataModel],
10+
pages = [
11+
"Home" => "index.md",
12+
"API" => "api.md",
13+
],
14+
checkdocs = :exports,
15+
doctest = true,
16+
warnonly = Documenter.except(:doctest),
17+
)
18+
19+
deploydocs(
20+
repo = "github.com/JuliaSpacePhysics/SpaceDataModel.jl",
21+
push_preview = true
22+
)

‎docs/src/api.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# API Reference
2+
3+
## Public
4+
5+
```@autodocs
6+
Modules = [SpaceDataModel]
7+
Private = false
8+
```
9+
10+
## Private
11+
12+
```@autodocs
13+
Modules = [SpaceDataModel]
14+
Public = false
15+
Order = [:function]
16+
```

‎docs/src/index.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# SpaceDataModel.jl
2+
3+
SpaceDataModel.jl is a lightweight Julia package providing a flexible data model for handling space/heliospheric science data. It offers abstractions for organizing space data into hierarchical structures including projects, instruments, datasets, and data variables.
4+
5+
It is used in [SPEDAS.jl](https://github.com/Beforerr/SPEDAS.jl), [Speasy.jl](https://github.com/SciQLop/Speasy.jl), and [HAPIClient.jl](https://github.com/JuliaSpacePhysics/HAPIClient.jl).
6+
7+
## Installation
8+
9+
```julia
10+
using Pkg
11+
Pkg.add("SpaceDataModel")
12+
```
13+
14+
## Usage
15+
16+
```julia
17+
using SpaceDataModel
18+
19+
# Create a project
20+
project = Project(; name="Project Name")
21+
instrument = Instrument(; name="Instrument Name")
22+
dataset = DataSet(name="Dataset Name")
23+
24+
push!(project, instrument, dataset)
25+
push!(instrument, dataset)
26+
```
27+
28+
See [Data Model and Project Module - SPEDAS.jl](https://beforerr.github.io/SPEDAS.jl/dev/explanations/data_model/) for more details.
29+
30+
## Features
31+
32+
- Hierarchical organization of data (projects, instruments, datasets)
33+
- Pretty printing for data inspection
34+
35+
## Reference
36+
37+
- [SPASE Model](https://spase-group.org/data/model/index.html)
38+
- [HAPI Data Access Specification](https://github.com/hapi-server/data-specification)
39+
- [CommonDataModel.jl](https://github.com/JuliaGeo/CommonDataModel.jl)
40+
- [NetCDF Data Model](https://docs.unidata.ucar.edu/netcdf-c/current/netcdf_data_model.html)

‎src/utils.jl‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ end
4848
4949
Return the field from a composite `v` for the given `name`, or the given `default` if no field is present.
5050
51-
See also: [`getfield`](@ref).
51+
See also: `getfield`.
5252
"""
5353
_getfield(v, name::Symbol, default=nothing) = hasfield(typeof(v), name) ? getfield(v, name) : default
5454
_getfield(v, names, default=Some(nothing)) = something(_getfield.(Ref(v), names)..., default) # no runtime cost

0 commit comments

Comments
 (0)