Step by Step Documentation Tutorial

Did you just start making an amazing package and want to document it? Failing miserably?
I was in your shoes a few days back and after a lot of drama I managed to get everything running. So I thought I would write a step by step tutorial on how to use Documenter.jl.


Hopefully it will help you out :slight_smile: Feedback would be really appreciated

Do check out the rest of the blog if you want too. I don’t track so I wouldn’t know if you did but if you are interested in Machine Learning you might like it.
PS. Huge shoutout to the people who made Documenter.jl . You are awesome!!


It might be a good idea to show how to set up TagBot to automatically push docs for stable versions as well. You need to add SSH keys for that, as described here:


Thank you. I will add that part to the tutorial too :slight_smile:

1 Like

I like this in that it’s more compact than what we have in the official manual. Just to put it out there: we’re always happy to take PRs for to make Documenter’s official documentation more accessible for new users :wink:

Just a few comments:

  1. PkgTemplates can actually generate Documenter configuration for you.

  2. Putting push!(LOAD_PATH,"../src/") into make.jl is not ideal.

    The recommended way is to have a separate project environment under docs (i.e. a docs/Project.toml file). The docs/ environment would take care of all the dependencies (i.e. Documenter, but also any other you may have, such as plotting libraries). The package itself should be added as a development dependency to that environment when the docs/ environment gets instantiated.

    When cloning a clean repository, the environment can be instantiated with e.g.:

    $ julia --project=docs/
    pkg> instantiate
    pkg> dev .
    julia> include("docs/make.jl")
  3. Point 10 under sections “How” seems to have some formatting problems.

  4. Hosting things under the docs/ directory on the master branch is not recommended. Instead, it’s better to put the generated content onto a separate gh-pages branch and host from there. The Hosting Documentation section deals with all that.


Well you have an awesome documentation but I thought it would be nice to put it in a workflow of sorts for people new to Julia. :slight_smile:
To be very honest I did not know these points myself.
Thank you!

Haha let me fix these changes that you mentioned in the post and maybe I’ll drop a PR with this on the official documentation. Is that okay?
I guess it would help a lot of people who are doing this for the first time and might not have even coded before.


This could work well as a quickstart section (the Guide page is a bit verbose, and only covers part of what’s needed for a package). That said, nothing wrong with having them as external resources. Ultimately, up to you, but we definitely won’t say no to documentation PRs :slight_smile:

1 Like

Ah I got caught up with some work but finally got around to sending a PR. And I added it as an internal resource and not as a link. :slight_smile:
Here is the PR. Link

1 Like

Can someone provide a step-by-step commands of what that means? Currently I have one project in which I have the docs in the /docs folder, and when I generate the pages with “make.jl” the page goes into the “/docs/build” directory, as expected. This directory is, however, excluded from commits in the “.gitignore” file.

I have created the gh-branch, but for now the project home-page points to the file.

The step-by-step provided by @SubhadityaMukherjee would be a very nice addition to the docs of Documenter.

Documenter is a really great package, but I find the default docs, while very comprehensive, quite difficult to follow, there is a lot of terminology there which one needs to understand before following the them. I ended up understanding how to use it by copying some examples. Then, when trying to deploy the docs, I installed the Travis “thing” without understanding what it is for, and finally gave up on hosting the page on github, ending hosting it in a private server. I am sure that at the end deploying the docs reduces to copying a couple of files to “.github/workflows”, or something like that, but I got lost in the path.

Please keep in mind that


Before I do something stupid, is it safe to use package templates in a project already half setup? Will it overwrite the files I have already in place? (of course, if it does, I can get them back from the repository).

Commit everything to the git repo first, then you can cherry-pick the changes suggested by the template generator.


I used the PkgTemplates, and it seems that the files I cherry-picked worked somehow. The Actions are running with no errors (I had to add a “Pkg.add("Documenter")” in a julia -e... line of ci.yml, but that fixed the error.

The make.jl is not throwing any error, and I created the gh-pages branch.

Still, I do not see that the build directory of the docs are saved anywhere, and the project page continues to point to the file.

The package where I am trying to configure this is this one:

Currently I have the docs hosted at “”.

I am not sure if you have access to this, but the actions log is here, and seems to be fine:

This is what I do for my packages. I will post it here in case it corresponds to what you wish to do:

  1. Create the structure of the documentation.
  2. Generate keys.
pkg"add DocumenterTools"  
using DocumenterTools
DocumenterTools.genkeys(user="PetrKryslUCSD", repo="")
  1. The above code will print out instructions for this step. Set the keys: Github repo settings.

    And Travis repo settings.
  2. Update Travis configuration.
  3. Next time CI is run (if without errors) will execute the build of the documentation and upload the documentation to gh-pages.

Thanks, I added the keys now, but the rendered documentation was not uploaded. :frowning:

The documentation is built during Travis testing, and uploaded by Travis. It is not built locally.

What is your repo? Post a CI link please.

I am using github actions instead of Travis, and I have verified that the actions ran after the keys where added. I might not know, perhaps, where the docs finally get hosted.

The repo is:

The CI file is:

For FinEtools the gh-pages are at

Why your gh-pages branch is not visible? Is it created like any other branch?

(I am asking this to see if I find what is missing in my configuration)

Since I don’t use actions, the display of the repo may be different?