Skip to content

Commit

Permalink
upgrade to Documenter.jl v1
Browse files Browse the repository at this point in the history
  • Loading branch information
marius311 committed Oct 5, 2023
1 parent 469e1f7 commit b693772
Show file tree
Hide file tree
Showing 10 changed files with 420 additions and 292 deletions.
2 changes: 1 addition & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`)
Expand Down
567 changes: 344 additions & 223 deletions docs/Manifest.toml

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions docs/Project.toml
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"

[compat]
CUDA = "3.4"
Documenter = "1.1"

[preferences.FFTW]
provider = "fftw"
124 changes: 65 additions & 59 deletions docs/make.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand All @@ -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


Expand All @@ -159,6 +164,7 @@ makedocs(
"precompilation.md",
"api.md"
],
remotes = nothing
)

if haskey(ENV, "IMAGE_NAME")
Expand Down
6 changes: 3 additions & 3 deletions docs/src/01_lense_a_map.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
);
```

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -125,4 +125,4 @@ Once cached, it's faster and less memory intensive to repeatedly apply the opera
@benchmark* 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).
2 changes: 1 addition & 1 deletion docs/src/03_joint_MAP_example.md
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
2 changes: 1 addition & 1 deletion docs/src/04_from_python.md
Original file line number Diff line number Diff line change
Expand Up @@ -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("""
Expand Down
2 changes: 1 addition & 1 deletion src/chains.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion src/dataset.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit b693772

Please sign in to comment.