Skip to content

Instantly share code, notes, and snippets.

@kalmarek
Created November 12, 2023 15:28
Show Gist options
  • Save kalmarek/1447407e0cad32ea4cb4443977009a39 to your computer and use it in GitHub Desktop.
Save kalmarek/1447407e0cad32ea4cb4443977009a39 to your computer and use it in GitHub Desktop.
Documenter.jl fast paced github setting up guide

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 live1 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 SettingsPages
    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 SettingsDeploy keys with read/write access,
  • add the private key to SettingsSecrets and variablesActions 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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment