Update docs readme

conda-env/dev.yml

@@ -29,16 +29,6 @@ dependencies:
  - rasterio=1.3.6
  - shapely=2.0.1
  # ==================
- # Documentation
- # ==================
- - sphinx=5.3.0
- - sphinx-autosummary-accessors=2022.4.0
- - sphinx-book-theme=1.0.1
- - sphinx-copybutton=0.5.1
- - nbsphinx=0.9.1
- - pandoc=3.1.1
- - ipython=8.11.0 # Required for nbsphinx syntax highlighting
- # ==================
  # Testing
  # ==================
  - pre_commit=3.2.2
@@ -50,5 +40,15 @@ dependencies:
  - jupyterlab=3.6.3
  - nb_conda=2.2.1
  - nb_conda_kernels=2.3.1
+ # ==================
+ # Documentation
+ # ==================
+ - sphinx=5.3.0
+ - sphinx-autosummary-accessors=2022.4.0
+ - sphinx-book-theme=1.0.1
+ - sphinx-copybutton=0.5.1
+ - nbsphinx=0.9.1
+ - pandoc=3.1.1
+ - ipython=8.11.0 # Required for nbsphinx syntax highlighting
 
 prefix: /opt/miniconda3/envs/pmcdi_metrics_dev

conda-env/readthedocs.yml

@@ -38,7 +38,7 @@ dependencies:
  # ==================
  - jupyterlab=3.6.3
  - nb_conda=2.2.1
- - nb_conda_kernels=2.3.1 
+ - nb_conda_kernels=2.3.1
  # ==================
  # Documentation
  # ==================

docs/README.md

@@ -1,41 +1,39 @@
-CURRENTLY TESTING ...
----------------------
+Update Documentation website
+----------------------------
+This directory hosts the online documentation for the PCMDI Metrics packages. There are two options available, one via Github Pages (http: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.
 
-
-readthedocs
------------
-This directory hosts the online documentation for the PCMDI Metrics packages (https://pcmdi-metrics.readthedocs.io). Provided here are instructions for updating the documentation.
-
-Checking out and making changes to the docs branch:
----------------------------------------------------
-
-You must be in a conda environment with "sphinx", "sphinx_rtd_theme", and other sphinx-related libraries listed in `conda-env/readthedocs.yml` installed. Otherwise, create your env following below
+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/readthedocs.yml
+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 for local preview
---------------------------
+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.
+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.
 
-Build for readthedocs
----------------------
-After building, you then have to "git add" all the files you updated.
+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:
 ```
@@ -44,8 +42,8 @@ git commit -m "your message"
 ```
 Then you can push your changes.
 
-Pushing your changes to your fork to preview:
----------------------------------------------
+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>
@@ -58,6 +56,14 @@ 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 merged, go to readthedocs (https://readthedocs.org/projects/pcmdi-metrics/) to build web pages.
+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 accssible at http: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 accessbile at https://pcmdi-metrics.readthedocs.io/en/latest/.
+
+Resources
+---------
+* [Read the Docs tutorial](https://docs.readthedocs.io/en/stable/tutorial/index.html)
+* [Deploying Sphinx documentation to GitHub Pages](https://coderefinery.github.io/documentation/gh_workflow/)
+