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 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: Hosting Documentation · Documenter.jl
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
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")
Point 10 under sections “How” seems to have some formatting problems.
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.
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
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 @mortenpi
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.
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).
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.
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.
Feedback would be really appreciated
