Documentation on Github Pages#
The procedure below describes the steps to follow in order to publish documentation pages from a new repository in the Scipp organisation to the scipp.github.io website.
In this example, we assume that the new repository is named
ess (the full path including organisation is hence
All documentation must go in a
docs folder located at the root of the repository.
nbsphinx) to transform
.rst files and Jupyter notebooks into html pages.
git clone email@example.com:scipp/ess.git
Create a gh-pages branch on the repository with
git checkout -b gh-pages
On Github, go to the repository
Settings > Pages(you will need admin rights to see the
Settingstab). You should see that it is now saying “Your site is published at
https://scipp.github.io/ess/”. It should also be saying it is using the
gh-pagesbranch and the
On your local machine, generate a ssh key, without an email or passphrase:
ssh-keygen -t rsa -b 4096. When prompted for a file name, use
Go to the repository’s
Settings > Deploy keys. Add a new key, and copy the contents of the
gh_pages_deploy_key.pubfile. Remember to also give the key
writeaccess to the repository.
Go to the project page on Azure. Go to
Pipelines > Library. Open the Variable Group named
tokensif it already exists, if not create one.
Copy/paste the contents of the
gh_pages_deploy_key.pubfile into a new secret variable named
Still in the Azure project’s library, go to
Pipelines > Library > Secure Files. Upload the
gh_pages_deploy_key(the private key of the pair without the
.pub) file as a secure file.
On your local machine, to back to where you cloned the
essgit repository. Create a new branch starting from the
git checkout mainthen
git checkout -b deploy_docs.
In that new branch, enable docs deployment in the
.azure-pipelines/release.ymlfiles, by simply setting
Push the changes to github (
git push origin deploy_docs) and create a pull request. Hopefully, once the pull request is merged into
mainthe pages will show up on https://scipp.github.io/ess.
An alternative to this last step is, instead of waiting for the PR to be merged, one can just change the “branches trigger” in the
main.yml and at the same time disable publishing of new packages as a temporary change.