Documenter.jl fast paced github setting up guide

fast_paced_gh.md

Fast paced github setting up guide

Situation

You have your own repository on github.com/username/MyPackage.jl with a julia package and would like to write and deploy documentation for it using Documenter.jl.

Step 0 - Prerequisites

Install DocumenterTools.jl:

julia> using Pkg; Pkg.add("DocumenterTools")

Step 1 - Package structure

Start julia wherever your package is available and using DocumenterTools.jl generate the basic docs structure.

julia> using DocumenterTools

julia> using MyPackage

julia> DocumenterTools.generate(MyPackage)
[ Info: deploying documentation to `/tmp/MyPackage/docs`
[ Info: Generating .gitignore at /tmp/MyPackage/docs/.gitignore
[ Info: Generating make.jl at /tmp/MyPackage/docs/make.jl
[ Info: Generating Project.toml at /tmp/MyPackage/docs/Project.toml
[ Info: Generating src/index.md at /tmp/MyPackage/docs/src/index.md

The directory structure should look something like this now

shell> tree MyPackage
MyPackage
├── docs
│   ├── make.jl
│   ├── Project.toml
│   └── src
│       └── index.md
├── Manifest.toml
├── Project.toml
└── src
    └── MyPackage.jl

Step 2 - Prepare docs/make.jl

You need to modify docs/make.jl manually so that it looks like this:

using Documenter, MyPackage

DocMeta.setdocmeta!(MyPackage, :DocTestSetup, :(using MyPackage); recursive = true)
# this is useful so that you can access your package functions in docs directly 

makedocs(
    sitename = "MyPackage.jl",
    modules = [MyPackage],
    pages = [
        "index.md",
        "Important Section" => [
            "First Subsection" => "section01.md",
            "Second Subsection" => "section02.md",
            # ...
        ],
        "Some loose comments" => "comments.md",
        # ...
    ],
    warnonly = [:missing_docs], # otherwise making docs will throw on missing docstrings
)

deploydocs(repo = "github.com/username/MyPackage.jl")

Step 3 - Write your documentation!

Place the .md files with docs into docs/src/ and don't forget to include them in docs/make.jl.

To view live¹ the docs you may use LiveServer.jl, in particular servedocs function is your friend.

Step 4 - Deploy

When satisfied with the result of the previous step:

1. Add the appropriate Github Action to your project (.github/workflows/documentation.yml).
2. In the action file correct the name of the default branch if needed (is it main? master? trunk?)
3. Go to Settings of your repository on github.com and enable GitHub Pages:
   1. navigate to Settings → Pages
   2. in Build and deployment select Deploy from branch and specify gh-pages and /(root) as the source

If you now make a pull request with your documentation you should see the Documentation action kicking in, and if everything is fine it will pass (but not deploy yet!). If you merge the PR to your repository the action will run and deploy your beautifully written docs. It may take a while, but the docs will be available under username.github.io/MyPackage.jl/, huraay!

Step 5 - TagBot itegration

You are probably also using Julia TagBot to tag a new release whenever a new version is registered in General repository. To deploy docs for every version created from now on there is one last step that needs to be done: DOCUMENTER_KEY. You may read about it in the bottom part of this paragraph, but long story short is that TagBot authenticated via GITHUB_TOKEN (the default) has permissions to create new tags, but not to trigger another action (hereDocumentation). To authenticate the bot we're going to use DocumenterTools.jl again:

julia> using DocumenterTools

julia> using MyPackage

julia> DocumenterTools.genkeys(MyPackage)

You'll see public-private ssh-key pair together with helpful instructions. To summarize you need to

• add the public key to Settings → Deploy keys with read/write access,
• add the private key to Settings → Secrets and variables → Actions under Repository secrets.

Et voilà!, your odyssey of documenting the package is now complete!

Footnotes

1. Note that servedocs will live-update the documentation pages, but NOT the docstrings! ↩