Skip to content

Commit

Permalink
Merge pull request #952 from PCMDI/update_docs_readme
Browse files Browse the repository at this point in the history
Update docs readme
  • Loading branch information
lee1043 authored Jun 22, 2023
2 parents 27b369f + bba1238 commit ad8a947
Show file tree
Hide file tree
Showing 3 changed files with 40 additions and 34 deletions.
20 changes: 10 additions & 10 deletions conda-env/dev.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
2 changes: 1 addition & 1 deletion conda-env/readthedocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
# ==================
Expand Down
52 changes: 29 additions & 23 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -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://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:
```
Expand All @@ -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>
Expand All @@ -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://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/)

0 comments on commit ad8a947

Please sign in to comment.