diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml index b03e41e4e6..3b923376a6 100644 --- a/.github/workflows/Documentation.yml +++ b/.github/workflows/Documentation.yml @@ -7,7 +7,7 @@ on: - cron: '15 2 * * *' # 2:15 AM UTC every day jobs: docs: - name: Documentation + name: MultiDocumentation runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 @@ -15,7 +15,16 @@ jobs: with: version: "1" - uses: julia-actions/cache@v2 - - uses: julia-actions/julia-docdeploy@v1 + - name: Install dependencies + shell: julia --color=yes --project=docs {0} + run: | + using Pkg + Pkg.instantiate() + - name: Aggregate and deploy + run: | + git config user.name github-actions + git config user.email github-actions@github.com + julia --color=yes --project=docs docs/make.jl --deploy env: DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/docs/Project.toml b/docs/Project.toml index 0640d86a6d..e1148730bf 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,5 +1,6 @@ [deps] Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +MultiDocumenter = "87ed4bf0-c935-4a67-83c3-2a03bee4197c" Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f" [compat] diff --git a/docs/make.jl b/docs/make.jl index 81d2eebe3a..cd1b01580e 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,25 +1,23 @@ -using LibGit2, Pkg, TOML, UUIDs +using MultiDocumenter, Documenter +using LibGit2, Pkg, TOML, UUIDs, Downloads # This make file compiles the documentation for the JuliaAstro website. -# It consists of the usual documeter structure, but also follows the approach +# It consists of the usual documenter structure, but also follows the approach # of the SciML docs page https://github.com/SciML/SciMLDocs/blob/main/docs/make.jl # by generating nested documentation for packages under the JuliaAstro organization. -# That way, docs for all packages are browesable and searchable in one place! +# That way, docs for all packages are browsable and searchable in one place! -include("install.jl") +clonedir = ("--temp" in ARGS) ? mktempdir(; cleanup=false) : joinpath(@__DIR__, "clones") +outpath = ("--temp" in ARGS) ? mktempdir(; cleanup=false) : joinpath(@__DIR__, "build") -for depe in to_use - eval(quote - using $depe - push!(allmods, $depe) - end) -end +@info """ +Cloning packages into: $(clonedir) +Building aggregate site into: $(outpath) +""" -# We wait to import Documenter in case one of the packages requires -# an older version. If that was the case, it's version may have changed -# after the above for-loop -using Documenter +@info "Building MultiDocumenter site for JuliaAstro" +include("pages.jl") mathengine = MathJax3(Dict( :loader => Dict("load" => ["[tex]/require", "[tex]/mathtools"]), :tex => Dict( @@ -31,25 +29,285 @@ mathengine = MathJax3(Dict( makedocs( sitename="JuliaAstro", authors = "Julia Astro Contributors", - modules=identity.(allmods), clean=true, doctest=false, format=Documenter.HTML( mathengine=mathengine, prettyurls = get(ENV, "CI", "false") == "true", - canonical = "https://juliaastro.github.io/", + canonical = "https://juliaastro.org/", assets = String[ "assets/styles.css", + "assets/favicon.ico", ], ), pages=fullpages, warnonly=[:missing_docs], ) +@info "Building aggregate JuliaAstro site" +docs = [ + # We also add JuliaAstro's own generated pages + MultiDocumenter.MultiDocRef( + upstream = joinpath(@__DIR__, "build"), + path = "docs", + name = "JuliaAstro", + fix_canonical_url = false, + ), + MultiDocumenter.DropdownNav( + "Time, Coordinates, & Units", + [ + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "AstroAngles"), + path = "AstroAngles", + name = "AstroAngles", + giturl = "https://github.com/JuliaAstro/AstroAngles.jl.git", + ), + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "AstroTime"), + path = "AstroTime", + name = "AstroTime", + giturl = "https://github.com/JuliaAstro/AstroTime.jl.git", + ), + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "ERFA"), + path = "ERFA", + name = "ERFA", + giturl = "https://github.com/JuliaAstro/ERFA.jl.git", + ), + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "SkyCoords"), + path = "SkyCoords", + name = "SkyCoords", + giturl = "https://github.com/JuliaAstro/SkyCoords.jl.git", + ), + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "UnitfulAstro"), + path = "UnitfulAstro", + name = "UnitfulAstro", + giturl = "https://github.com/JuliaAstro/UnitfulAstro.jl.git", + ), + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "WCS"), + path = "WCS", + name = "WCS", + giturl = "https://github.com/JuliaAstro/WCS.jl.git", + ), + ] + ), + MultiDocumenter.DropdownNav( + "Images", + [ + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "AstroImages"), + path = "AstroImages", + name = "AstroImages", + giturl = "https://github.com/JuliaAstro/AstroImages.jl.git", + ), + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "SAOImagesDS9"), + path = "SAOImagesDS9", + name = "SAOImagesDS9", + giturl = "https://github.com/JuliaAstro/SAOImageDS9.jl.git", + ), + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "Photometry"), + path = "Photometry", + name = "Photometry", + giturl = "https://github.com/juliaastro/Photometry.jl.git", + ), + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "PSFModels"), + path = "PSFModels", + name = "PSFModels", + giturl = "https://github.com/juliaastro/PSFModels.jl.git", + ), + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "LACosmic"), + path = "LACosmic", + name = "LACosmic", + giturl = "https://github.com/juliaastro/LACosmic.jl.git", + ), + ] + ), + MultiDocumenter.DropdownNav( + "Data I/O", + [ + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "AstroImages"), + path = "AstroImages", + name = "AstroImages", + giturl = "https://github.com/JuliaAstro/AstroImages.jl.git", + ), + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "FITSIO"), + path = "FITSIO", + name = "FITSIO", + giturl = "https://github.com/JuliaAstro/FITSIO.jl.git", + ), + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "CFITSIO"), + path = "CFITSIO", + name = "CFITSIO", + giturl = "https://github.com/JuliaAstro/CFITSIO.jl.git", + ), + MultiDocumenter.Link( + "mweastwood/CasaCore", + "http://mweastwood.info/CasaCore.jl/stable/", + ), + MultiDocumenter.Link( + "emmt/OIFITS", + "https://github.com/emmt/OIFITS.jl", + ), + MultiDocumenter.Link( + "aplavin/VLBIData", + "https://github.com/JuliaAPlavin/VLBIData.jl", + ), + MultiDocumenter.Link( + "aplavin/Difmap", + "https://github.com/JuliaAPlavin/Difmap.jl", + ), + ] + ), + MultiDocumenter.DropdownNav( + "Cosmology", + [ + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "Cosmology"), + path = "Cosmology", + name = "Cosmology", + giturl = "https://github.com/JuliaAstro/Cosmology.jl.git", + ), + ] + ), + MultiDocumenter.DropdownNav( + "Orbits & Ephemerides", + [ + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "Transits"), + path = "Transits", + name = "Transits", + giturl = "https://github.com/JuliaAstro/Transits.jl.git", + ), + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "sefffal/PlanetOrbits"), + path = "sefffal/PlanetOrbits", + name = "sefffal/PlanetOrbits", + giturl = "https://github.com/sefffal/PlanetOrbits.jl.git", + ), + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "EarthOrientation"), + path = "EarthOrientation", + name = "EarthOrientation", + giturl = "https://github.com/JuliaAstro/EarthOrientation.jl.git", + ), + MultiDocumenter.Link( + "JPLEphemeris", + "https://github.com/JuliaAstro/JPLEphemeris.jl", + ), + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "AstroLib"), + path = "AstroLib", + name = "AstroLib", + giturl = "https://github.com/JuliaAstro/AstroLib.jl.git", + ), + ] + ), + MultiDocumenter.DropdownNav( + "Numerical Utilities", + [ + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "BoxLeastSquares"), + path = "BoxLeastSquares", + name = "BoxLeastSquares", + giturl = "https://github.com/JuliaAstro/BoxLeastSquares.jl.git", + ), + MultiDocumenter.MultiDocRef( + upstream = joinpath(clonedir, "LombScargle"), + path = "LombScargle", + name = "LombScargle", + giturl = "https://github.com/JuliaAstro/LombScargle.jl.git", + ), + ] + ), + MultiDocumenter.DropdownNav( + "Statistics", + [ + MultiDocumenter.Link( + "sefffal/PairPlots", + "https://sefffal.github.io/PairPlots.jl/dev", + ), + ] + ), +] + +MultiDocumenter.make( + outpath, + docs; + assets_dir = "docs/src/assets", + search_engine = MultiDocumenter.SearchConfig( + index_versions = ["stable"], + engine = MultiDocumenter.FlexSearch + ), + rootpath = "/previews/PR43/", + canonical_domain = "https://JuliaAstro.org/", + brand_image = MultiDocumenter.BrandImage(".", joinpath("assets", "logo.svg")), + sitemap = true, +) +@info "Aggregate build done" + +# Download logo +assets_dir = joinpath(outpath, "assets") +mkpath(assets_dir) +Downloads.download( + "https://raw.githubusercontent.com/JuliaAstro/JuliaAstro.github.io/refs/heads/source/docs/src/assets/logo.svg", + joinpath(assets_dir, "logo.svg"); + verbose = true, +) +@info "Final build done" + +@info "Deployng docs" +#if "--deploy" in ARGS +# @warn "Deploying to GitHub" ARGS +# gitroot = normpath(joinpath(@__DIR__, "..")) +# run(`git pull`) +# outbranch = "master" +# has_outbranch = true +# if !success(`git checkout $outbranch`) +# has_outbranch = false +# if !success(`git switch --orphan $outbranch`) +# @error "Cannot create new orphaned branch $outbranch." +# exit(1) +# end +# end +# for file in readdir(gitroot; join = true) +# (endswith(file, ".git") || (basename(file) == "CNAME")) && continue +# rm(file; force = true, recursive = true) +# end +# for file in readdir(outpath) +# cp(joinpath(outpath, file), joinpath(gitroot, file)) +# end +# run(`git add .`) +# if success(`git commit -m 'Aggregate documentation'`) +# @info "Pushing updated documentation." +# if has_outbranch +# run(`git push`) +# else +# run(`git push -u origin $outbranch`) +# end +# run(`git checkout source`) +# else +# @info "No changes to aggregated documentation." +# end +#else +# @info "Skipping deployment, 'deploy' not passed. Generated files in docs/$(outpath)." ARGS +# cp(outpath, joinpath(@__DIR__, "build"), force = true) +#end deploydocs(; repo = "github.com/JuliaAstro/JuliaAstro.github.io", push_preview = true, branch = "master", - devbranch = "source" + devbranch = "source", + versions = nothing, ) +@info "Deploy complete" diff --git a/docs/pages.jl b/docs/pages.jl index 6f875f73e5..914be0bdea 100644 --- a/docs/pages.jl +++ b/docs/pages.jl @@ -2,7 +2,7 @@ # Plain documenter pages fullpages = Any[ - "Home"=>"index.md" + "Home"=>"index.md", # "Ecosystem" => "ecosystem.md"; "Tutorials" => [ "tutorials/index.md", @@ -11,118 +11,12 @@ fullpages = Any[ "tutorials/tabular-data.md", "tutorials/curve-fit.md", ] - ] -] - -# Categories to pull in from external docs -# Ordering Matters! -docsmodules = [ - "Time, Coordinates, & Units" => [ - "AstroLib", - "UnitfulAstro", - "AstroAngles", - "AstroTime", - "SkyCoords", - "WCS", - ], - "Images" => [ - "AstroImages", - "SAOImageDS9", - "Photometry", - "PSFModels", - #"CCDReduction", - "LACosmic", - "SkyImages", - ], - "Data I/O" => [ - "FITSIO", - "CFITSIO", - "CasaCore", - "OIFITS", - "VLBIData", - "Difmap", - "VOTables", - "VirtualObservatory", ], - "Cosmology" => [ - "Cosmology" - ], - "Orbits & Emphemerides" => [ - # "JPLEphemeris", - "EarthOrientation", - "Transits", - "PlanetOrbits", - "AstroLib", - ], - "Numerical Utilities" => [ - "BoxLeastSquares", - "LombScargle" - ], - "Statistics" => [ - "PairPlots" - ] + "Time, Coordinates, & Units" => "highlevels/timecoords.md", + "Images" => "highlevels/images.md", + "Data I/O" => "highlevels/dataio.md", + "Cosmology" => "highlevels/cosmology.md", + "Orbits & Emphemerides" => "highlevels/orb-ephem.md", + "Numerical Utilities" => "highlevels/numerical-utils.md", + "Statistics" => "highlevels/stats.md", ] - - -# Intro pages to a given category. -# Ensure order matches the above. -catpagestarts = [ - Any["highlevels/timecoords.md"], - Any["highlevels/images.md"], - Any["highlevels/dataio.md"], - Any["highlevels/cosmology.md"], - Any["highlevels/orb-ephem.md"], - Any["highlevels/numerical-utils.md"], - Any["highlevels/stats.md"], -] - -# 3rd party packages: pull in README only -usereadme = Dict( - - # These are breaking the build for some reason - "PSFModels" => "https://github.com/JuliaAstro/PSFModels.jl", - # "LACosmic" => "https://github.com/JuliaAstro/LACosmic.jl", - "Transits" => "https://github.com/JuliaAstro/Transits.jl", - - # No docs page yet - "AstroAngles" => "https://github.com/JuliaAstro/AstroAngles.jl", - - # Ecosystem - "CasaCore" => "https://github.com/mweastwood/CasaCore.jl", - "Difmap" => "https://github.com/JuliaAPlavin/Difmap.jl", - "OIFITS" => "https://github.com/emmt/OIFITS.jl", - "PairPlots" => "https://github.com/sefffal/PairPlots.jl", - "PlanetOrbits" => "https://github.com/sefffal/PlanetOrbits.jl", - "SkyImages" => "https://github.com/JuliaAPlavin/SkyImages.jl", - "VLBIData" => "https://github.com/JuliaAPlavin/VLBIData.jl", - "VOTables" => "https://github.com/JuliaAPlavin/VOTables.jl", - "VirtualObservatory" => "https://github.com/JuliaAPlavin/VirtualObservatory.jl", -) - -# Specify revision to install and build docs for. -# Every package must be listed here UNLESS it's listed in `usereadme` above. -pkgrevs = Dict( - "AstroAngles" => "main", - "AstroImages" => "master", - "AstroLib" => "master", - "AstroLib" => "master", - "AstroTime" => "main", - "BoxLeastSquares" => "main", - # "CCDReduction" => "main", - "CFITSIO" => "master", - "Cosmology" => "master", - "DustExtinction" => "master", - "EarthOrientation" => "master", - "ERFA" => "main", - "FITSIO" => "master", - "LACosmic" => "main", - #"JPLEphemeris" => "master", - "LombScargle" => "master", - "Photometry" => "main", - # "PSFModels" => "main", - "SAOImageDS9" => "master", - "SkyCoords" => "master", - # "Transits" => "main", - "UnitfulAstro" => "master", - "WCS" => "master", -) diff --git a/docs/src/ecosystem.md b/docs/src/ecosystem.md index 1339de9524..a7f7c67c86 100644 --- a/docs/src/ecosystem.md +++ b/docs/src/ecosystem.md @@ -235,6 +235,8 @@ The joy of our community is the many astronomy and astrophysics packages availab [![curly braces](assets/code.png) Repository](https://github.com/JuliaAstro/AstroAngles.jl) +[![book icon](assets/book.png) Documentation](https://juliaastro.org/AstroAngles.jl/dev/) + **String parsing and representation of angles** - Parse and represent sexagesimal angles with a variety of delimiters diff --git a/docs/src/highlevels/timecoords.md b/docs/src/highlevels/timecoords.md index 9098822314..269407f9c8 100644 --- a/docs/src/highlevels/timecoords.md +++ b/docs/src/highlevels/timecoords.md @@ -4,6 +4,8 @@ [![curly braces](../assets/code.png) Repository](https://github.com/JuliaAstro/AstroAngles.jl) +[![book icon](../assets/book.png) Documentation](https://juliaastro.org/AstroAngles.jl/dev/) + **String parsing and representation of angles** - Parse and represent sexagesimal angles with a variety of delimiters