Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation API description #1141

Merged
merged 29 commits into from
Sep 25, 2024
Merged
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
41a66fa
Update conf.py
lee1043 Sep 25, 2024
adf7510
Update and rename utils.rst to api.rst
lee1043 Sep 25, 2024
837733c
Merge pull request #1142 from PCMDI/lee1043-patch-2
lee1043 Sep 25, 2024
61ff114
Update resources.rst
lee1043 Sep 25, 2024
b3f3ca4
Update dev.yml
lee1043 Sep 25, 2024
9162158
Update conf.py
lee1043 Sep 25, 2024
368d278
Update conf.py
lee1043 Sep 25, 2024
78259e5
Update documentation.yaml
lee1043 Sep 25, 2024
0a2f881
Update conf.py
lee1043 Sep 25, 2024
82f68ae
Update documentation.yaml
lee1043 Sep 25, 2024
9b75c64
Update documentation.yaml
lee1043 Sep 25, 2024
b935330
Update api.rst
lee1043 Sep 25, 2024
92d8eeb
Update api.rst
lee1043 Sep 25, 2024
de4b4a9
remove readthedocs components
lee1043 Sep 25, 2024
9ff48bf
add import pcmdi_metrics
lee1043 Sep 25, 2024
1591361
run only when PR merged; add steps to get pcmdi_metrics installed so …
lee1043 Sep 25, 2024
f5b9c6e
refer dev.yml when generating conda env
lee1043 Sep 25, 2024
02825d6
update
lee1043 Sep 25, 2024
a57d7cd
combined to build_workflow.yml
lee1043 Sep 25, 2024
3540742
clean up
lee1043 Sep 25, 2024
901fd59
orgarnize functions into categories
lee1043 Sep 25, 2024
bf3d378
separate ci.yml from dev.yml to make lighter env for build
lee1043 Sep 25, 2024
5dc94cb
add docstrings
lee1043 Sep 25, 2024
f3468f6
add more functions to the list
lee1043 Sep 25, 2024
0130387
add docstrings
lee1043 Sep 25, 2024
867620c
add more functions to the list
lee1043 Sep 25, 2024
d99cf17
rewrite docstring to scipy style
lee1043 Sep 25, 2024
9ea275a
clean up
lee1043 Sep 25, 2024
79e5355
test
lee1043 Sep 25, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 79 additions & 6 deletions .github/workflows/build_workflow.yml
Original file line number Diff line number Diff line change
@@ -56,9 +56,10 @@ jobs:
- name: Set up Conda Environment
uses: conda-incubator/setup-miniconda@v2
with:
activate-environment: "pcmdi_metrics_dev"
activate-environment: "pcmdi_metrics_ci"
miniforge-variant: Mambaforge
miniforge-version: latest
environment-file: conda-env/ci.yml
use-mamba: true
mamba-version: "*"
channel-priority: strict
@@ -83,11 +84,6 @@ jobs:
# Increase this value to reset cache if conda/dev.yml has not changed in the workflow
CACHE_NUMBER: 0

- name: Update environment
run:
mamba env update -n pcmdi_metrics_dev -f conda-env/dev.yml
if: steps.cache.outputs.cache-hit != 'true'

- name: Install pcmdi_metrics
# Source: https://github.com/conda/conda-build/issues/4251#issuecomment-1053460542
run: |
@@ -96,3 +92,80 @@ jobs:
- name: Run Tests
run: |
pytest

- name: Run Unit Tests
run: pytest tests


publish-docs:
if: ${{ github.event_name == 'push' }}
runs-on: ubuntu-latest
defaults:
run:
shell: bash -l {0}
timeout-minutes: 5
steps:
- uses: actions/checkout@v3
with:
persist-credentials: false
fetch-depth: 0

- name: Cache Conda
uses: actions/cache@v3
env:
# Increase this value to reset cache if conda-env/ci.yml has not changed in the workflow
CACHE_NUMBER: 0
with:
path: ~/conda_pkgs_dir
key: ${{ runner.os }}-conda-${{ env.CACHE_NUMBER }}-${{
hashFiles('conda-env/ci.yml') }}

- name: Set up Conda Environment
uses: conda-incubator/setup-miniconda@v2
with:
activate-environment: "pcmdi_metrics_dev"
miniforge-variant: Miniforge3
miniforge-version: latest
environment-file: conda-env/dev.yml
channel-priority: strict
auto-update-conda: true

- name: Build Sphinx Docs
run: |
cd docs
sphinx-multiversion source _build/html

- name: Copy Docs and Commit
run: |
# gh-pages branch must already exist
git clone https://github.com/PCMDI/pcmdi_metrics.git --branch gh-pages --single-branch gh-pages

# Make sure we're in the gh-pages directory.
cd gh-pages

# Create `.nojekyll` (if it doesn't already exist) for proper GH Pages configuration.
touch .nojekyll

# Add `index.html` to point to the `main` branch automatically.
printf '<meta http-equiv="refresh" content="0; url=./_build/html/main/index.html" />' > index.html

# Only replace `main` docs with latest changes. Docs for tags should be untouched.
rm -rf _build/html/main
mkdir -p _build/html/main
cp -r ../docs/_build/html/main _build/html

# Configure git using GitHub Actions credentials.
git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
git config --local user.name "github-actions[bot]"

# The below command will fail if no changes were present, so we ignore it
git add .
git commit -m "Update documentation" -a || true

- name: Push Changes
uses: ad-m/github-push-action@master
with:
branch: gh-pages
directory: gh-pages
github_token: ${{ secrets.GITHUB_TOKEN }}
force: true
24 changes: 0 additions & 24 deletions .github/workflows/documentation.yaml

This file was deleted.

23 changes: 0 additions & 23 deletions .readthedocs.yaml

This file was deleted.

35 changes: 11 additions & 24 deletions conda-env/readthedocs.yml → conda-env/ci.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
name: pcmdi_metrics_rtd
# Conda pcmdi_metrics CI/CD environment (used in GH Actions).
name: pcmdi_metrics_ci
channels:
- conda-forge
- defaults
@@ -10,43 +11,29 @@ dependencies:
- python=3.10.10
- pip=23.1.2
- numpy=1.23.5
- cartopy=0.21.1
- cartopy=0.22.0
- matplotlib=3.7.1
- cdms2=3.1.5
- genutil=8.2.1
- cdutil=8.2.1
- cdp=1.7.0
- eofs=1.4.0
- eofs=1.4.1
- seaborn=0.12.2
- enso_metrics=1.1.1
- xcdat=0.5.0
- xcdat>=0.7.0
- xmltodict=0.13.0
- setuptools=67.7.2
- netcdf4=1.6.3
- netcdf4>=1.6.3
- regionmask=0.9.0
- rasterio=1.3.6
- rasterio>=1.3.6
- shapely=2.0.1
- numdifftools
- nc-time-axis
# ==================
# Testing
# ==================
- pre_commit=3.2.2
- pytest=7.3.1
- pytest-cov=4.0.0
# ==================
# Developer Tools
# ==================
- 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/pcmdi_metrics_rtd

prefix: /opt/miniconda3/envs/pmcdi_metrics_ci
4 changes: 3 additions & 1 deletion conda-env/dev.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Conda pcmdi_metrics development environment
# A conda development environment with all dependencies, including optional and documentation dependencies.
name: pcmdi_metrics_dev
channels:
- conda-forge
@@ -45,11 +45,13 @@ dependencies:
# Documentation
# ==================
- sphinx
- sphinx-autosummary-accessors
- sphinx-book-theme
- sphinx-copybutton
- sphinx_rtd_theme
- nbsphinx
- pandoc
- sphinx-design
- ipython # Required for nbsphinx syntax highlighting

prefix: /opt/miniconda3/envs/pmcdi_metrics_dev
34 changes: 34 additions & 0 deletions docs/_templates/autosummary/class.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. add toctree option to make autodoc generate the pages

.. autoclass:: {{ objname }}

{% block attributes %}
{% if attributes %}
.. rubric:: Attributes

.. autosummary::
:toctree: .
{% for item in attributes %}
~{{ name }}.{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

{% block methods %}
{% if methods %}
.. rubric:: Methods

.. autosummary::
:toctree: .
{% for item in methods %}
{%- if item != '__init__' %}
~{{ name }}.{{ item }}
{%- endif -%}
{%- endfor %}
{% endif %}
{% endblock %}

90 changes: 90 additions & 0 deletions docs/api.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
API Reference
=============

API Functions for Developpers
-----------------------------

.. currentmodule:: pcmdi_metrics

Below is a list of some API functions that are available in `pcmdi_metrics.` for developpers.


Land-sea mask
~~~~~~~~~~~~~

.. autosummary::
:toctree: generated/

pcmdi_metrics.utils.create_land_sea_mask
pcmdi_metrics.utils.apply_landmask
pcmdi_metrics.utils.apply_oceanmask


Grid handling and re-gridding (horizontal interpolation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autosummary::
:toctree: generated/

pcmdi_metrics.utils.create_target_grid
pcmdi_metrics.utils.regrid


Quality control (QC)
~~~~~~~~~~~~~~~~~~~~

.. autosummary::
:toctree: generated/

pcmdi_metrics.utils.check_daily_time_axis
pcmdi_metrics.utils.check_monthly_time_axis


Calendar-related functions
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autosummary::
:toctree: generated/

pcmdi_metrics.utils.custom_season_average
pcmdi_metrics.utils.custom_season_departure


Miscellaneous tools
~~~~~~~~~~~~~~~~~~~
.. autosummary::
:toctree: generated/

pcmdi_metrics.utils.sort_human
pcmdi_metrics.utils.fill_template
pcmdi_metrics.utils.tree


Region handling
~~~~~~~~~~~~~~~
.. autosummary::
:toctree: generated/

pcmdi_metrics.io.region_subset
pcmdi_metrics.io.region_from_file


Retrieve data from xarray Dataset
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autosummary::
:toctree: generated/

pcmdi_metrics.io.get_grid
pcmdi_metrics.io.get_axis_list
pcmdi_metrics.io.get_data_list
pcmdi_metrics.io.get_latitude
pcmdi_metrics.io.get_latitude_bounds
pcmdi_metrics.io.get_latitude_key
pcmdi_metrics.io.get_longitude
pcmdi_metrics.io.get_longitude_bounds
pcmdi_metrics.io.get_longitude_key
pcmdi_metrics.io.get_time
pcmdi_metrics.io.get_time_bounds
pcmdi_metrics.io.get_time_bounds_key
pcmdi_metrics.io.get_time_key
pcmdi_metrics.io.select_subset

Loading