upgrade to Documenter.jl v1

marius311 · Oct 5, 2023 · b693772 · b693772
1 parent 469e1f7
commit b693772
Show file tree

Hide file tree

Showing 10 changed files with 420 additions and 292 deletions.
diff --git a/Dockerfile b/Dockerfile
@@ -31,7 +31,7 @@ RUN apt-get update \
 
 ## install julia
 RUN mkdir /opt/julia \
-    && curl -L https://julialang-s3.julialang.org/bin/linux/x64/1.9/julia-1.9.0-rc2-linux-x86_64.tar.gz | tar zxf - -C /opt/julia --strip=1 \
+    && curl -L https://julialang-s3.julialang.org/bin/linux/x64/1.9/julia-1.9.3-linux-x86_64.tar.gz | tar zxf - -C /opt/julia --strip=1 \
     && chown -R 1000 /opt/julia \
     && ln -s /opt/julia/bin/julia /usr/local/bin
 

diff --git a/README.md b/README.md
@@ -30,14 +30,14 @@ The best place to get started is to read the [documentation](https://cosmicmar.c
 
 Most of the pages in the documentation are Jupyter notebooks, and you can click the "launch binder" link at the top of each page to launch a Jupyterlab server running the notebook in your browser (courtesy of [binder](https://mybinder.org/)). 
 
-You can also clone the repository and open the notebooks in [docs/src](https://github.com/marius311/CMBLensing.jl/tree/master/docs/src) if you want to run them locally (which will usually lead to higher performance). The notebooks are stored as `.md` files rather than `.ipynb` format. Its recommended to install [Jupytext](jupytext) (`pip install jupytext`) and then you can run these `.md` directly from Jupyterlab by right-clicking on them and selecting `Open With -> Notebook`. Otherwise, run the script `docs/make_notebooks.sh` to convert the `.md` files to `.ipynb` which you can then open as desired. 
+You can also clone the repository and open the notebooks in [docs/src](https://github.com/marius311/CMBLensing.jl/tree/master/docs/src) if you want to run them locally (which will usually lead to higher performance). The notebooks are stored as `.md` files rather than `.ipynb` format. Its recommended to install [Jupytext](https://jupytext.readthedocs.io/en/latest/) (`pip install jupytext`) and then you can run these `.md` directly from Jupyterlab by right-clicking on them and selecting `Open With -> Notebook`. Otherwise, run the script `docs/make_notebooks.sh` to convert the `.md` files to `.ipynb` which you can then open as desired. 
 
 
 ## Installation
 
 ### Requirements
 
-* Julia 1.7+
+* Julia 1.8+
 * _(recommended)_ An Nvidia GPU and [CUDA.jl](https://github.com/JuliaGPU/CUDA.jl) for GPU support
 * _(recommended)_ Python 3 + matplotlib (used for plotting)
 * _(recommended)_ [pycamb](https://github.com/cmbant/CAMB) to generate $C_\ell$'s (run `pip install --user camb`)

diff --git a/docs/Manifest.toml b/docs/Manifest.toml
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -18,6 +18,7 @@ Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 
 [compat]
 CUDA = "3.4"
+Documenter = "1.1"
 
 [preferences.FFTW]
 provider = "fftw"
diff --git a/docs/make.jl b/docs/make.jl
@@ -37,12 +37,15 @@ rm("src-staging/index.md",force=true)
 symlink("../../README.md","src-staging/index.md")
 
 
-# highlight output cells (i.e. anything withouout a language specified) white
-# note: "output" language is added by us in documenter.tpl
-@eval Documenter.Writers.HTMLWriter function mdconvert(c::Markdown.Code, parent::MDBlockContext; settings::Union{HTML,Nothing}=nothing, kwargs...)
+# # highlight output cells (i.e. anything withouout a language specified) white
+# # note: "output" language is added by us in documenter.tpl
+@eval Documenter.Writers.HTMLWriter function domify(dctx::DCtx, node::Node, c::MarkdownAST.CodeBlock)
+    ctx, navnode, settings = dctx.ctx, dctx.navnode, dctx.settings
+    language = c.info
+    # function mdconvert(c::Markdown.Code, parent::MDBlockContext; settings::Union{HTML,Nothing}=nothing, kwargs...)
     @tags pre code
-    language = Utilities.codelang(c.language)
-    if language == "documenter-ansi" || language == "output" # From @repl blocks (through MultiCodeBlock)
+    language = Documenter.codelang(language)
+    if language == "documenter-ansi" || language == "output"
         return pre(domify_ansicoloredtext(c.code, "language-output hljs"))
     elseif settings !== nothing && settings.prerender &&
            !(isempty(language) || language == "nohighlight")
@@ -53,90 +56,92 @@ symlink("../../README.md","src-staging/index.md")
     return pre(code[".$(class) .hljs"](c.code))
 end
 
+
 # adds the MyBinder button on each page that is a notebook
 @eval Documenter.Writers.HTMLWriter function render_navbar(ctx, navnode, edit_page_link::Bool)
     @tags div header nav ul li a span img
 
+    # Hamburger on mobile
+    navbar_left = a[
+        "#documenter-sidebar-button.docs-sidebar-button.docs-navbar-link.fa-solid.fa-bars.is-hidden-desktop",
+        :href => "#",
+    ]
+
     # The breadcrumb (navigation links on top)
-    navpath = Documents.navpath(navnode)
+    navpath = Documenter.navpath(navnode)
     header_links = map(navpath) do nn
-        title = mdconvert(pagetitle(ctx, nn); droplinks=true)
+        dctx = DCtx(ctx, nn, true)
+        title = domify(dctx, pagetitle(dctx))
         nn.page === nothing ? li(a[".is-disabled"](title)) : li(a[:href => navhref(ctx, nn, navnode)](title))
     end
     header_links[end] = header_links[end][".is-active"]
-    breadcrumb = nav[".breadcrumb"]() ### modified to not show breadcrumbs
+    breadcrumb = nav[".breadcrumb"](
+        ul[".is-hidden-mobile"](header_links),
+        ul[".is-hidden-tablet"](header_links[end]) # when on mobile, we only show the page title, basically
+    )
 
     # The "Edit on GitHub" links and the hamburger to open the sidebar (on mobile) float right
     navbar_right = div[".docs-right"]
-
-    ### custom code to add MyBinder link
-    if edit_page_link
-        pageurl = get(getpage(ctx, navnode).globals.meta, :EditURL, getpage(ctx, navnode).source)
-        nbpath = foldl(replace,["src-staging"=>"src",".md"=>".ipynb"], init=pageurl)
-        if isfile(nbpath)
-            url = "https://mybinder.org/v2/gh/marius311/CMBLensing.jl/gh-pages?urlpath=lab/tree/$(basename(nbpath))"
-            push!(navbar_right.nodes, a[".docs-right", :href => url](img[:src => "https://mybinder.org/badge_logo.svg"]()))
+
+        ### custom code to add MyBinder link
+        if edit_page_link
+            pageurl = get(getpage(ctx, navnode).globals.meta, :EditURL, getpage(ctx, navnode).source)
+            nbpath = foldl(replace,["src-staging"=>"src",".md"=>".ipynb"], init=pageurl)
+            if isfile(nbpath)
+                url = "https://mybinder.org/v2/gh/marius311/CMBLensing.jl/gh-pages?urlpath=lab/tree/$(basename(nbpath))"
+                push!(navbar_right.nodes, a[".docs-right", :href => url](img[:src => "https://mybinder.org/badge_logo.svg"]()))
+            end
         end
-    end
-    ###
+        ###
 
-    # Set the logo and name for the "Edit on.." button.
-    if edit_page_link && (ctx.settings.edit_link !== nothing) && !ctx.settings.disable_git
-        host_type = Utilities.repo_host_from_url(ctx.doc.user.repo)
-        if host_type == Utilities.RepoGitlab
-            host = "GitLab"
-            logo = "\uf296"
-        elseif host_type == Utilities.RepoGithub
-            host = "GitHub"
-            logo = "\uf09b"
-        elseif host_type == Utilities.RepoBitbucket
-            host = "BitBucket"
-            logo = "\uf171"
-        else
-            host = ""
-            logo = "\uf15c"
-        end
-        hoststring = isempty(host) ? " source" : " on $(host)"
-
-        pageurl = get(getpage(ctx, navnode).globals.meta, :EditURL, getpage(ctx, navnode).source)
-
-
-        edit_branch = isa(ctx.settings.edit_link, String) ? ctx.settings.edit_link : nothing
-        url = if Utilities.isabsurl(pageurl)
-            pageurl
-        else
-            if !(pageurl == getpage(ctx, navnode).source)
-                # need to set users path relative the page itself
-                pageurl = joinpath(first(splitdir(getpage(ctx, navnode).source)), pageurl)
-            end
-            Utilities.url(ctx.doc.user.repo, pageurl, commit=edit_branch)
+
+    # Set up the link to the root of the remote Git repository
+    #
+    # By default, we try to determine it from the configured remote. If that fails, the link
+    # is not displayed. The user can also pass `repolink` to HTML to either disable it
+    # (repolink = nothing) or override the link URL (if set to a string). In the latter case,
+    # we try to figure out what icon and string we should use based on the URL.
+    if !isnothing(ctx.settings.repolink) && (ctx.settings.repolink isa String || ctx.doc.user.remote isa Remotes.Remote)
+        url, (host, logo) = if ctx.settings.repolink isa String
+            ctx.settings.repolink, host_logo(ctx.settings.repolink)
+        else # ctx.doc.user.remote isa Remotes.Remote
+            Remotes.repourl(ctx.doc.user.remote), host_logo(ctx.doc.user.remote)
         end
-        if url !== nothing
-            edit_verb = (edit_branch === nothing) ? "View" : "Edit"
-            title = "$(edit_verb)$hoststring"
+        # repourl() can sometimes return a nothing (Remotes.URL)
+        if !isnothing(url)
+            repo_title = "View the repository" * (isempty(host) ? "" : " on $host")
             push!(navbar_right.nodes,
-                a[".docs-edit-link", :href => url, :title => title](
-                    span[".docs-icon.fab"](logo),
-                    span[".docs-label.is-hidden-touch"](title)
+                a[".docs-navbar-link", :href => url, :title => repo_title](
+                    span[".docs-icon.fa-brands"](logo),
+                    span[".docs-label.is-hidden-touch"](isempty(host) ? "Repository" : host)
                 )
             )
         end
     end
+    # Add an edit link, with just an icon, but only on pages where edit_page_link is true.
+    # Some pages, like search, are special and do not have a source file to link to.
+    edit_page_link && edit_link(ctx, navnode) do logo, title, url
+        push!(navbar_right.nodes,
+            a[".docs-navbar-link", :href => url, :title => title](
+                span[".docs-icon.fa-solid"](logo)
+            )
+        )
+    end
 
     # Settings cog
     push!(navbar_right.nodes, a[
-        "#documenter-settings-button.docs-settings-button.fas.fa-cog",
+        "#documenter-settings-button.docs-settings-button.docs-navbar-link.fa-solid.fa-gear",
         :href => "#", :title => "Settings",
     ])
 
-    # Hamburger on mobile
+    # Collapse/Expand All articles toggle
     push!(navbar_right.nodes, a[
-        "#documenter-sidebar-button.docs-sidebar-button.fa.fa-bars.is-hidden-desktop",
-        :href => "#"
+        "#documenter-article-toggle-button.docs-article-toggle-button.fa-solid.fa-chevron-up",
+        :href=>"javascript:;", :title=>"Collapse all docstrings",
     ])
 
     # Construct the main <header> node that should be the first element in div.docs-main
-    header[".docs-navbar"](breadcrumb, navbar_right)
+    header[".docs-navbar"](navbar_left, breadcrumb, navbar_right)
 end
 
 
@@ -159,6 +164,7 @@ makedocs(
         "precompilation.md",
         "api.md"
     ],
+    remotes = nothing
 )
 
 if haskey(ENV, "IMAGE_NAME")

diff --git a/docs/src/01_lense_a_map.md b/docs/src/01_lense_a_map.md
@@ -32,7 +32,7 @@ First we load a simulated unlensed field, $f$, and lensing potential, $\phi$,
     θpix  = 2,       # size of the pixels in arcmin
     Nside = 256,     # number of pixels per side in the map
     T     = Float32, # Float32 or Float64 (former is ~twice as fast)
-    pol   = :I,       # :I for Intensity, :P for polarization, or :IP for both=
+    pol   = :I,      # :I for Intensity, :P for polarization, or :IP for both
 );
 ```
 
@@ -69,7 +69,7 @@ If you have your own map data in an array you'd like to load into a CMBLensing `
 FlatMap(mapdata, θpix=3)
 ```
 
-For more info on `Field` objects, see [Field Basics](../05_field_basics/).
+For more info on `Field` objects, see [Field Basics](05_field_basics.md).
 
 
 ## Inverse lensing
@@ -125,4 +125,4 @@ Once cached, it's faster and less memory intensive to repeatedly apply the opera
 @benchmark Lϕ * f setup=(Lϕ=precompute!!(LenseFlow(ϕ),f))
 ```
 
-Note that this documentation is generated on limited-performance cloud servers. Actual benchmarks are likely much faster locally or on a cluster, and yet (much) faster on [GPU](../06_gpu/).
+Note that this documentation is generated on limited-performance cloud servers. Actual benchmarks are likely much faster locally or on a cluster, and yet (much) faster on [GPU](06_gpu.md).
diff --git a/docs/src/03_joint_MAP_example.md b/docs/src/03_joint_MAP_example.md
@@ -123,7 +123,7 @@ fJ, ϕJ, history = MAP_joint(ds, nsteps=30, progress=true);
 # Examine results
 
 
-The `history` variable gives some info about the run, and more info can be saved by passing `history_keys` argument to [`MAP_joint`](api/#CMBLensing.MAP_joint). By default, we get just the value of the posterior, which we can use to check the maximizer has asymptoted to a maximum value:
+The `history` variable gives some info about the run, and more info can be saved by passing `history_keys` argument to `MAP_joint`. By default, we get just the value of the posterior, which we can use to check the maximizer has asymptoted to a maximum value:
 
 ```julia
 plot(getindex.(history, :logpdf))

diff --git a/docs/src/04_from_python.md b/docs/src/04_from_python.md
@@ -69,7 +69,7 @@ jl.seval("1:10")
 ## Calling CMBLensing.jl
 
 
-You can use `seval` to essentially just paste Julia code into Python session, for example, following the [Lensing a flat-sky map](../01_lense_a_map/) example:
+You can use `seval` to essentially just paste Julia code into Python session, for example, following the [Lensing a flat-sky map](01_lense_a_map.md) example:
 
 ```python
 jl.seval("""

diff --git a/src/chains.jl b/src/chains.jl
@@ -17,7 +17,7 @@ Keyword arguments:
   `thin == :hasmaps`, return only samples which have maps saved. If
   thin is a `Function`, filter the chain by this function (e.g.
   `thin=haskey(:g)` on Julia 1.5+)
-* `unbatch` — If true, [unbatch](@ref) the chains if they are batched.
+* `unbatch` — If true, run `unbatch` on the chains if they are batched.
 * `join` — If true, concatenate all the chains together.
 * `skip_missing_chunks` — Skip missing chunks in the chain instead of
   terminating the chain there. 

diff --git a/src/dataset.jl b/src/dataset.jl
@@ -323,7 +323,7 @@ function load_sim(;
         ds.D = ParamDependentOp(
             function (;r=r₀, _...)
                 Cfr = Cf(;r=r)
-                sqrt((Cfr + I*σ²len + 2*Cn̂) * pinv(Cfr))
+                sqrt((Cfr + (I*σ²len + 2*Cn̂)) * pinv(Cfr))
             end,
         )
     end