-
Notifications
You must be signed in to change notification settings - Fork 40
Github page maintenance
Online documentation for the PCMDI Metrics packages is maintained via github page. Provided here are instructions for updating the documentation.
You must be in a conda environment with "sphinx" and "sphinx_rtd_theme" installed
git pull origin main (optional, grab latest updates)
git checkout -b <new branch name>
cd docs
The source files are found in pcmdi_metrics/docs/source. There is an index.rst file that is the landing page. If you create a new page, make sure to list it under the toctree in index.rst.
cd pcmdi_metrics/docs
make clean
make html
The make clean command is optional and deletes the existing docs/build folder, which is populated by make html.
To view your changes locally, open pcmdi_metrics/docs/build/html/index.html with a browser. If it does not build as expected, first try running make clean before building again.
The main difference here is that the web files have to be copied to /docs. There is a command that does builds and copies in one step:
cd pcmdi_metrics/docs
make github
Alternatively, these are the manual steps to build for github:
cd pcmdi_metrics/docs
make clean
make html
cp -r build/html/* .
After building, you then have to "git add" all the files you copied from build/html and commit before pushing. This includes *html, *inv, and *js files, along with the _sources and _static folders (which are currently listed in .gitignore, so you have to make sure to add them) For example:
git add source/*rst *html *inv *js _static _sources
git commit -m "your message"
Then you can push your changes
In pcmdi_metrics, set up your fork as a remote:
git remote add <remote name> <https://github.com/your_fork_path>
git remote -v
Checkout and push your changes:
git checkout <branch with changes>
git push <remote name> <branch with changes>
Then go to your forked repo on github.com. Go to Settings -> GitHub Pages -> Source. Under source, select the name of the branch you just pushed. Choose /docs as the folder. This will generate a link to your github pages site.
You can also open a pull request from your fork repo, if desired.