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 (1) the docs you may use LiveServer.jl, in particular servedocs function is your friend.
[1]: servedocs will live-update the documentation pages, but NOT the docstrings!
Step 4 - Deploy
When satisfied with the result of the previous step:
- Add the appropriate Github Action to your project (.github/workflows/documentation.yml).
- In the action file correct the name of the default branch if needed (is it main? master? trunk?)
- Go to Settings of your repository on github.com and enable GitHub Pages:
- navigate to Settings → Pages
- 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!