The best tool I know for that is
LiveServer and its
servedocs() function. Just do:
julia> ] activate docs julia> using LiveServer julia> servedocs()
and the docs will be rendered and hosted locally at the url provided in the output.
import DocumenterTools DocumenterTools.genkeys()
which will output something like:
julia> DocumenterTools.genkeys() [ Info: add the public key below to https://github.com/$USER/$REPO/settings/keys with read/write access: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDIIDDRX8DyLG... CCKQPTNei1Ng8b5d+a1ldnVSkgB0= Documenter [ Info: add a secure environment variable named 'DOCUMENTER_KEY' to https://travis-ci.com/$USER/$REPO/settings (if you deploy using Travis CI) or https://github.com/$USER/$REPO/settings/secrets (if you deploy using GitHub Actions) with value: LS0tLS1CRUdJTiBPUEVOU1NIIFBSSV... MGtyNng2VWR6WTFxckg1bkUyVGU2ajU3TUdveXpZL1EzTApoNGlqbE5NSWJTOFA2K2JNUkYxVFVCUzdQbC9mZDlTZWJKYTlKdWpMamtnNWRiblJFSkpESmpDTzNzSjZ4d0VCUmV2WmJSCnZtV2lkWkVnQnlPUFVsQUFBQUNrUnZZM1Z0Wlc1MFpYST0KLS0tLS1FTkQgT1BFTlNTSCBQUklWQVRFIEtFWS0tLS0tCg==
The first key, starting with
ssh-rsa must be copied as a new "Deploy key` in the project, at:
Settings -> Deploy keys -> Add deploy key
Be careful in allowing
Write permissions. The second key has to be copied to:
Settings -> Secrets -> New repository secret
with the name
Create, in your project, a file
with a content similar to THIS one.
Note that you have to change some lines that contain the name of the package name (
JuliaNotes - two substitutions).
Go to the github page. Go to
Draft a new Release. Create a new tag for the new version (for example,
v0.2.0) or a tag only for deploying the documentation (for example,
v0.1.0+doc1). That will trigger the execution of the CI run and, hopefully, build the docs and the
gh-branch that contain the docs automatically.
The pages will be hosted at, for example:
You can also update the docs just by uploading a new tag, with:
git tag -a v0.1.0+doc2 -m "v0.1.0" git push --tag
I have seen these steps happening automatically after the tag is created. If not, follow the steps below.
Create a branch on the repository called
git checkout --orphan gh-pages git reset --hard git commit --allow-empty -m "Initializing gh-pages branch" git push origin gh-pages git checkout main
In the GitHub repository, do:
Settings -> GitHub Pages -> choose gh-pages (/root)
(that is, go to Seetings, scroll down, on the GitHub pages section, choose the
gh-pages banch to deploy your page).
After the end of the CI run, if no error was detected, the site should be published.
In this case, you might want
TagBot to tag and release automatically the documentation of new versions:
and add the content provided here: TagBot.yml example
I went to the registered commit, which always have the following information, for example:
git tag -a v0.4.11 -m "<description of version>" fbeec6a00adbd15053d297542e8354c457b2a610 git push origin v0.4.11
and created a new tag adding
+doc1 to the tag:
git tag -a v0.4.11+doc1 -m "v0.4.11" fbeec6a00adbd15053d297542e8354c457b2a610 git push origin v0.4.11+doc1
Then I had to go to the github page -> tags, and publish that release manually.
Further discussion: Latest version of docs not published