1

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.

POST

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!!

19 Likes
2

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: Hosting Documentation · Documenter.jl

3 Likes
4

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

1 Like
5

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.

5 Likes
6

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.

3 Likes
7

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
8

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
@mortenpi

1 Like
9

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 README.md 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.

10

Please keep in mind that

3 Likes
11

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).

12

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

3 Likes
13

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 README.md file.

The package where I am trying to configure this is this one: http://github.com/m3g/PDBTools

Currently I have the docs hosted at “http://m3g.iqm.unicamp.br/PDBTools”.

I am not sure if you have access to this, but the actions log is here, and seems to be fine: https://github.com/m3g/PDBTools/actions/runs/263936622

14

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.
    image
  2. Generate keys.
pkg"add DocumenterTools"  
using DocumenterTools
DocumenterTools.genkeys(user="PetrKryslUCSD", repo="git@github.com:PetrKryslUCSD/FinEtools.jl.git")
  1. The above code will print out instructions for this step. Set the keys: Github repo settings.
    ScreenHunter 449
    ScreenHunter 4491383×370 19.3 KB

    And Travis repo settings.
    image
    image1467×641 31.7 KB
  2. Update Travis configuration.
    https://github.com/PetrKryslUCSD/FinEtools.jl/blob/master/.travis.yml
  3. Next time CI is run (if without errors) will execute the build of the documentation and upload the documentation to gh-pages.
4 Likes
15

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

16

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

17

What is your repo? Post a CI link please.

18

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:

https://github.com/m3g/PDBTools

The CI file is:

https://github.com/m3g/PDBTools/blob/master/.github/workflows/ci.yml

19

For FinEtools the gh-pages are at Home · FinEtools.jl

20

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

https://github.com/PetrKryslUCSD/FinEtools.jl/tree/gh-pages/docs

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

21

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