Skip to content

Latest commit

 

History

History

docs

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
_static
_static
 
 
Makefile
Makefile
 
 
README.md
README.md
 
 
conf.py
conf.py
 
 
contributing.rst
contributing.rst
 
 
index.rst
index.rst
 
 
install.rst
install.rst
 
 
make.bat
make.bat
 
 
metrics.rst
metrics.rst
 
 
metrics_enso.rst
metrics_enso.rst
 
 
metrics_ext.rst
metrics_ext.rst
 
 
metrics_mean-clim.rst
metrics_mean-clim.rst
 
 
metrics_mjo.rst
metrics_mjo.rst
 
 
metrics_monsoon.rst
metrics_monsoon.rst
 
 
metrics_mov.rst
metrics_mov.rst
 
 
metrics_precip-distribution.rst
metrics_precip-distribution.rst
 
 
metrics_precip-variability.rst
metrics_precip-variability.rst
 
 
metrics_sea_ice.rst
metrics_sea_ice.rst
 
 
metrics_subdaily-precipitation.rst
metrics_subdaily-precipitation.rst
 
 
overview.rst
overview.rst
 
 
pmp-using-cdp-guide.rst
pmp-using-cdp-guide.rst
 
 
pmpparser.rst
pmpparser.rst
 
 
resources.rst
resources.rst
 
 
start.rst
start.rst
 
 
supporting-data.rst
supporting-data.rst
 
 
team.rst
team.rst
 
 

README.md

Update Documentation website

This directory hosts the online documentation for the PCMDI Metrics packages. There are two options available, one via Github Pages (https://pcmdi.github.io/pcmdi_metrics/) and another via ReadtheDocs (https://pcmdi-metrics.readthedocs.io). Provided here are instructions for updating the documentation for either or both options.

Checking out and making changes

You must be in a conda environment with "sphinx", "sphinx_rtd_theme", and other sphinx-related libraries listed in conda-env/dev.yml installed. Otherwise, create your env following below

cd pcmdi_metrics
conda env create -n <new environment name> -f conda-env/dev.yml
conda activate <new environment name>

Once your environment is ready

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/. 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.

Building local preview

Optional but strongly recommended step is building a local preview to examine the generated html files are looking okay.

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.

Prepare pushing your changes

After previewing and everything look okay, you are ready to push changes. You have to "git add" all the files you updated.

For example:

git add *rst _static/*
git commit -m "your message"

Then you can push your changes.

Push your changes to remote

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 and create a Pull Request to the main branch.

Build webpages

Once the changes are merged to the main branch of pcmdi_metrics, Github Action will automatically build and deploy web pages using Github Pages. This process will follow what is defined in .github/workflows/documentation.yaml. The page will be accessible at https://pcmdi.github.io/pcmdi_metrics/.

To deploy the web pages via readthedocs, you will need to go to readthedocs project page (https://readthedocs.org/projects/pcmdi-metrics/), go to "Builds" menu, and click "Build Version" button. The page will be accessible at https://pcmdi-metrics.readthedocs.io/en/latest/.

Resources