# Step by Step Documentation Tutorial

**URL:** <https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093>\
**Category:** Community\
**Tags:** documentation, tutorials, blog-post\
**Created:** [September 5, 2020, 8:35am UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093 "2020-09-05T08:35:23Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![SubhadityaMukherjee](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/subhadityamukherjee/32/15983_2.png) [@SubhadityaMukherjee](https://discourse.julialang.org/u/SubhadityaMukherjee)\
**Post date:** [September 5, 2020, 8:35am UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/1 "2020-09-05T08:35:23Z")

</div>

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](https://juliadocs.github.io/Documenter.jl/stable/man/guide/#Navigation).

# [POST](https://www.subhadityamukherjee.me/2020/09/04/Documentation.html)

Hopefully it will help you out 🙂 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!!

---

<div class="post-metadata">

**Author:** ![simeonschaub](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/simeonschaub/32/216566_2.png) [@simeonschaub](https://discourse.julialang.org/u/simeonschaub)\
**Post date:** [September 5, 2020, 11:44am UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/2 "2020-09-05T11:44:34Z")

</div>

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](https://juliadocs.github.io/Documenter.jl/stable/man/hosting/#GitHub-Actions)

---

<div class="post-metadata">

**Author:** ![SubhadityaMukherjee](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/subhadityamukherjee/32/15983_2.png) [@SubhadityaMukherjee](https://discourse.julialang.org/u/SubhadityaMukherjee)\
**Post date:** [September 5, 2020, 12:26pm UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/4 "2020-09-05T12:26:02Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [September 6, 2020, 9:42am UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/5 "2020-09-06T09:42:22Z")

</div>

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 😉

Just a few comments:

1. PkgTemplates [can actually generate Documenter configuration for you](https://invenia.github.io/PkgTemplates.jl/stable/user/#PkgTemplates.Documenter).

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

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](https://juliadocs.github.io/Documenter.jl/stable/man/hosting/) deals with all that.

---

<div class="post-metadata">

**Author:** ![SubhadityaMukherjee](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/subhadityamukherjee/32/15983_2.png) [@SubhadityaMukherjee](https://discourse.julialang.org/u/SubhadityaMukherjee)\
**Post date:** [September 6, 2020, 9:56am UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/6 "2020-09-06T09:56:58Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [September 6, 2020, 11:05pm UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/7 "2020-09-06T23:05:31Z")

</div>

> [@SubhadityaMukherjee](#):
>
> 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?

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 🙂

---

<div class="post-metadata">

**Author:** ![SubhadityaMukherjee](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/subhadityamukherjee/32/15983_2.png) [@SubhadityaMukherjee](https://discourse.julialang.org/u/SubhadityaMukherjee)\
**Post date:** [September 20, 2020, 8:30am UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/8 "2020-09-20T08:30:23Z")

</div>

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. 🙂  
Here is the PR. [Link](https://github.com/JuliaDocs/Documenter.jl/pull/1419)  
@mortenpi

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [September 20, 2020, 1:23pm UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/9 "2020-09-20T13:23:30Z")

</div>

> [@mortenpi](#):
>
> 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.

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.

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [September 20, 2020, 1:37pm UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/10 "2020-09-20T13:37:07Z")

</div>

> [@lmiq](#):
>
> got lost in the path.

Please keep in mind that

> [@mortenpi](#):
>
> PkgTemplates [can actually generate Documenter configuration for you](https://invenia.github.io/PkgTemplates.jl/stable/user/#PkgTemplates.Documenter).

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [September 20, 2020, 1:50pm UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/11 "2020-09-20T13:50:27Z")

</div>

> [@Tamas\_Papp](#):
>
> 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).

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [September 20, 2020, 2:02pm UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/12 "2020-09-20T14:02:55Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [September 20, 2020, 5:42pm UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/13 "2020-09-20T17:42:18Z")

</div>

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](http://github.com/m3g/PDBTools)

Currently I have the docs hosted at “[http://m3g.iqm.unicamp.br/PDBTools](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](https://github.com/m3g/PDBTools/actions/runs/263936622)

---

<div class="post-metadata">

**Author:** ![PetrKryslUCSD](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/petrkryslucsd/32/215825_2.png) [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)\
**Post date:** [September 20, 2020, 5:57pm UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/14 "2020-09-20T17:57:59Z")

</div>

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](https://global.discourse-cdn.com/julialang/original/3X/1/b/1b20126ba2f3c80027fbd95ea59e18602bd1180d.png)
2. Generate keys.

```julia
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](https://global.discourse-cdn.com/julialang/original/3X/6/3/63288dad7b534d6eb275f0348ad24fc5e4b2d4a0.png)  
And Travis repo settings.  
 ![image](https://global.discourse-cdn.com/julialang/original/3X/0/a/0aeef25309e3cf89ac113a7aec1d61790be85cb2.png)
2. Update Travis configuration.  
[https://github.com/PetrKryslUCSD/FinEtools.jl/blob/master/.travis.yml](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`.

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [September 20, 2020, 6:16pm UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/15 "2020-09-20T18:16:50Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![PetrKryslUCSD](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/petrkryslucsd/32/215825_2.png) [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)\
**Post date:** [September 20, 2020, 6:20pm UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/16 "2020-09-20T18:20:32Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![PetrKryslUCSD](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/petrkryslucsd/32/215825_2.png) [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)\
**Post date:** [September 20, 2020, 6:21pm UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/17 "2020-09-20T18:21:02Z")

</div>

What is your repo? Post a CI link please.

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [September 20, 2020, 6:23pm UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/18 "2020-09-20T18:23:10Z")

</div>

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](https://github.com/m3g/PDBTools)

The CI file is:

[https://github.com/m3g/PDBTools/blob/master/.github/workflows/ci.yml](https://github.com/m3g/PDBTools/blob/master/.github/workflows/ci.yml)

---

<div class="post-metadata">

**Author:** ![PetrKryslUCSD](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/petrkryslucsd/32/215825_2.png) [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)\
**Post date:** [September 20, 2020, 6:28pm UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/19 "2020-09-20T18:28:13Z")

</div>

For FinEtools the gh-pages are at [Home · FinEtools.jl](https://petrkryslucsd.github.io/FinEtools.jl/latest/)

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [September 20, 2020, 6:35pm UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/20 "2020-09-20T18:35:28Z")

</div>

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](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)

---

<div class="post-metadata">

**Author:** ![PetrKryslUCSD](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/petrkryslucsd/32/215825_2.png) [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)\
**Post date:** [September 20, 2020, 7:26pm UTC](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093/21 "2020-09-20T19:26:32Z")

</div>

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

[Next page](https://discourse.julialang.org/t/step-by-step-documentation-tutorial/46093.md?page=2)