Skip to content

Latest commit

 

History

History
31 lines (19 loc) · 2.38 KB

devdocs.md

File metadata and controls

31 lines (19 loc) · 2.38 KB
Raw

ReTest

using ReTest, TestEnv
TestEnv.activate()
using CMBLensing
ReTest.hijack(CMBLensing, revise=true)
retest("filter", dry=false, verbose=2)

Documentation

  1. Run docker-compose up --build debug

  2. For notebooks, click link generated by the above command to open Jupyterlab. Edit notebooks as desired. Notebooks which have an .md file are Jupytext notebooks so make sure to edit that file (right click in Jupyterlab -> Open with Notebook), and not the .ipynb copy.

  3. For docs, run docker-compose exec -w /home/cosmo/CMBLensing/docs debug julia then include("make.jl") to refresh docs. The containers ~/.julia folder is a volume so future docker-compose exec shouldn't need a full recompile.

  4. Open browser to localhost:8000 to view docs.

  5. Once you're happy, do a full build by running docker-compose up --build main. If it works here, its should work when Github Actions builds the documentation from the notebooks and when the notebooks are launched by MyBinder, since this identical Docker container is used in both cases.

  6. Once the documentation is verified, commit changes to master or submit a PR. If you submit a PR, Github Actions will build a preview of the documentation for you, so you can check that rather than verifying locally if you like.

Other

The Github Actions workflow will build documentation for master and for all tags and PRs. It pushes these to the gh-pages branch of CMBLensing.jl which is then hosted at cosmicmar.com/CMBLensing.jl

All MyBinder links point to the gh-pages branch of CMBLensing.jl. MyBinder uses the Dockerfile in the root folder of this branch which is a symlink pointing to stable/Dockerfile, and stable/ is itself a symlink managed by Documenter.jl made to point at the most recent tagged version. This means MyBinder links from any version of the documentation will always point to the most recent stable tagged vesion (ideally they would point to whatever version the documenation itself was, but that's harder to set up).

The docker-compose.yml points to a Docker image tagged marius311/cmblensing.jl:stable. Its currently required to manually tag the most recent release with this name on Docker Hub (the image is built and tagged with the release number, so its just a matter of adding another tag, although in the future this should be automated with Github Actions too).