Step by Step Documentation Tutorial

@lmiq: It’s visible, it just doesn’t have a docs/ directory (https://github.com/PetrKryslUCSD/FinEtools.jl/tree/gh-pages/). Note that for the usual Documenter setups you wouldn’t have a docs/ directory there – the docs website files should be on the root of the gh-pages branch.

While not strictly necessary, gh-pages would ideally be an orhpan branch. I noticed that PDBTools’ gh-pages is actually forks the main branch. I would recommend you delete gh-pages and let Documenter create it for you.

Regarding the documentation not being deployed to GitHub pages: your make.jl doesn’t have a deploydocs call, which actually deploys the documentation. See The deploydocs Function in the Documenter manual.

1 Like

Thank you. I was actually finding out some of those errors and missing things, and I almost got there. I succeeded in deploying a dev version of the package, but I am still struggling to see a stable version as well. My deploydocs function looks like, now:

deploydocs(
    repo = "github.com/m3g/PDBTools.git",
    target = "build",
    branch = "gh-pages",
    versions = ["stable" => "v^", "v#.#" ],
)

I tested different things there, but no luck yet.

(ps. One small but annoying thing was that my repository does not have the “.jl” in its name. Therefore, where the docs say something like PACKAGE_NAME.jl.git I had to remove the .jl. Is it a recommended practice to add the .jl to the git repository?

For stable/ you need to tag a version and make sure that the CI runs for the tag. You have TagBot, so it should happen automatically for future releases.

Assuming that the master branch hasn’t diverged from v0.10.1 in terms of docs/functionality, you could manually create a tag v0.10.1+docs1 off the master branch, to test it. This should also deploy the docs for v0.10.1 (but be aware that the docstrings etc. in the manual will correspond to the newer tagged commit, not to the original v0.10.1 commit).

It’s not a requirement (i.e. the registry and the package manager do not care), but it is the usual practice to indicate that a repo is a Julia package by using that extension in the repo name.

3 Likes

Everything is working now, thank you all very much.

2 Likes