Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
14 changes: 7 additions & 7 deletions .github/workflows/build_conda.yml
Original file line number Diff line number Diff line change
Expand Up @@ -53,15 +53,15 @@ jobs:
echo "conda install conda-build"
conda install conda-forge::conda-build

- name: Build fremorizer Conda Package
- name: Build fremor Conda Package
run: |
echo "conda building fremorizer package and outputting as a tarball"
mkdir -p /tmp/fremorizer-tarball
conda build --package-format tar.bz2 --output-folder /tmp/fremorizer-tarball .
echo "conda building fremor package and outputting as a tarball"
mkdir -p /tmp/fremor-tarball
conda build --package-format tar.bz2 --output-folder /tmp/fremor-tarball .

- name: Upload fremorizer Tarball
- name: Upload fremor Tarball
uses: actions/upload-artifact@v4
with:
name: fremorizer-tarball
path: /tmp/fremorizer-tarball/noarch/fremorizer-*.tar.bz2
name: fremor-tarball
path: /tmp/fremor-tarball/noarch/fremor-*.tar.bz2
if-no-files-found: error
6 changes: 3 additions & 3 deletions .github/workflows/build_pip.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,14 +28,14 @@ jobs:
python -m pip install --upgrade pip
python -m pip install build

- name: Build fremorizer pip Package
- name: Build fremor pip Package
run: |
echo "Building fremorizer package using python -m build"
echo "Building fremor package using python -m build"
python -m build

- name: Upload pip Package Artifacts
uses: actions/upload-artifact@v4
with:
name: fremorizer-pip-packages
name: fremor-pip-packages
path: dist/*
if-no-files-found: error
4 changes: 2 additions & 2 deletions .github/workflows/create_test_conda_env.yml
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ jobs:
python-version: ${{ matrix.python-version }}
conda-remove-defaults: true
environment-file: environment.yaml
activate-environment: fremorizer
activate-environment: fremor

- name: Show installed packages
run: |
Expand All @@ -53,7 +53,7 @@ jobs:
echo "printing conda config just in case"
conda config --show

- name: Install fremorizer
- name: Install fremor
run: |
pip install .

Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/publish_conda.yml
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,8 @@ jobs:
echo "conda install conda-build"
conda install conda-forge::conda-build conda-forge::anaconda-client

- name: Build fremorizer Conda Package
- name: Build fremor Conda Package
run: |
echo "conda building fremorizer package"
echo "conda building fremor package"
export ANACONDA_API_TOKEN=${{ secrets.TEMP_ANACONDA_API_TOKEN }}
conda build .
4 changes: 2 additions & 2 deletions .github/workflows/pylint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ jobs:
- name: Setup Conda
uses: conda-incubator/setup-miniconda@v3
with:
activate-environment: fremorizer
activate-environment: fremor
environment-file: environment.yaml
auto-activate: false
miniforge-version: latest
Expand All @@ -46,7 +46,7 @@ jobs:
echo "printing conda config just in case"
conda config --show

- name: Install fremorizer
- name: Install fremor
run: |
pip install .

Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/wcrp_compliance_check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ jobs:
- name: Setup Conda
uses: conda-incubator/setup-miniconda@v3
with:
activate-environment: fremorizer-wcrp
activate-environment: fremor-wcrp
environment-file: environment.yaml
conda-remove-defaults: true
auto-activate: false
Expand All @@ -47,7 +47,7 @@ jobs:
echo "printing conda config just in case"
conda config --show

- name: Install fremorizer
- name: Install fremor
run: |
pip install .

Expand Down
2 changes: 1 addition & 1 deletion docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'fremorizer'
project = 'fremor'
copyright = f'{dt.datetime.now().year}, NOAA-GFDL MSD Workflow Team'
author = 'NOAA-GFDL MSD Workflow Team'
release = pkg_version # type: ignore
Expand Down
42 changes: 21 additions & 21 deletions docs/contributing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@ For Developers
==============

Developers should consult this section for detailed information relevant to development and maintenance
of ``fremorizer``, after familiarizing themselves with the rest of the user-targeted documentation.
of ``fremor``, after familiarizing themselves with the rest of the user-targeted documentation.


Contributing to ``fremorizer``
Contributing to ``fremor``
==============================


Expand All @@ -19,7 +19,7 @@ Get your own copy of the code:

.. code-block:: bash

git clone --recursive git@github.com:ilaflott/fremorizer.git
git clone --recursive git@github.com:ilaflott/fremor.git

Or replace with your fork's link (recommended).

Expand All @@ -29,16 +29,16 @@ Local/Editable Installation

Developers can test local changes by running ``pip install [-e] .`` inside of the root directory after
activating a virtual environment with ``python>=3.11`` and all requirements. This installs the
``fremorizer`` package locally with any local changes.
``fremor`` package locally with any local changes.

Development work on ``fremorizer`` should occur within a conda environment housing ``fremorizer``'s
Development work on ``fremor`` should occur within a conda environment housing ``fremor``'s
requirements, and a local copy of the repository installed with ``pip`` using the ``-e/--editable`` flag.

.. code-block:: bash

# Create the conda environment from environment.yaml
conda env create -f environment.yaml
conda activate fremorizer
conda activate fremor

# Install in editable mode
pip install -e .
Expand All @@ -48,7 +48,7 @@ Testing Your Local Changes
--------------------------

There are several ways to test your efforts locally during your development cycle. A few examples and
``fremorizer``-specific recommendations are described here, but contributors are welcome to be creative
``fremor``-specific recommendations are described here, but contributors are welcome to be creative
so long as they provide documentation of what they have contributed.

All contributed code should come with a corresponding unit test.
Expand All @@ -59,12 +59,12 @@ Running CLI Calls

Most development cycles will involve focused efforts isolated to a specific ``fremor COMMAND *ARGV``,
where ``*ARGV`` stands in for a shell-style argument vector (e.g. ``-d /path/to/input -l varlist.json``).
The code is housed in the ``fremorizer/`` package directory, with the ``click`` CLI entry-point in
``fremorizer/fremor.py``.
The code is housed in the ``fremor/`` package directory, with the ``click`` CLI entry-point in
``fremor/fremor.py``.

The developer usually uses ``fremor COMMAND *ARGV`` as a test, focused on seeing the changes they are
introducing, developing the code until the desired result is achieved. The specific ``fremor COMMAND *ARGV``
call can often become a unit test in one of the corresponding files in ``fremorizer/tests/``. The
call can often become a unit test in one of the corresponding files in ``fremor/tests/``. The
sought-after changes should become ``assert`` conditions encoded within the unit test. Both success and
failure conditions should ideally be tested.

Expand All @@ -74,18 +74,18 @@ Running Without ``click``

Every ``fremor COMMAND *ARGV`` approximately maps to a single function call (a ``*_subtool`` function
in the corresponding module). To remove ``click`` and the CLI aspect from testing, assuming the code
being executed is in ``fremorizer/cmor_mixer.py`` in a function called ``cmor_run_subtool``:
being executed is in ``fremor/cmor_mixer.py`` in a function called ``cmor_run_subtool``:

.. code-block:: bash

python -i -c 'from fremorizer.cmor_mixer import cmor_run_subtool; cmor_run_subtool(**args)'
python -i -c 'from fremor.cmor_mixer import cmor_run_subtool; cmor_run_subtool(**args)'


Writing ``pytest`` Unit Tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If the functionality to test is that of a CLI call, tests should use the ``CliRunner`` approach shown in
``fremorizer/tests/``. ``click``-based CLI calls should **not** be tested with ``subprocess.run`` within
``fremor/tests/``. ``click``-based CLI calls should **not** be tested with ``subprocess.run`` within
``pytest``. See `click's testing documentation <https://click.palletsprojects.com/en/stable/testing/>`_
for more information.

Expand All @@ -95,17 +95,17 @@ Run the test suite:

.. code-block:: bash

pytest fremorizer/tests/ -v
pytest fremor/tests/ -v


Running the Linter
~~~~~~~~~~~~~~~~~~

``fremorizer`` uses ``pylint`` for code quality checks:
``fremor`` uses ``pylint`` for code quality checks:

.. code-block:: bash

pylint --rcfile pylintrc fremorizer/
pylint --rcfile pylintrc fremor/


Adding a New Requirement
Expand All @@ -115,7 +115,7 @@ Currently, all required packages are ``conda`` packages listed in ``environment.
equivalently in ``meta.yaml``. ``conda`` packages that have a corresponding ``pip`` package should
also be listed in ``pyproject.toml``.

New dependencies for ``fremorizer`` must have a ``conda`` package available through a non-proprietary
New dependencies for ``fremor`` must have a ``conda`` package available through a non-proprietary
``conda`` channel, preferably the open-source ``conda-forge`` channel. Only ``conda-forge`` and
``noaa-gfdl`` channels are used.

Expand All @@ -125,10 +125,10 @@ functionality via standard-library approaches first, and be prepared to defend t
adding a new third-party package.


How ``fremorizer`` is Updated
How ``fremor`` is Updated
-----------------------------

``fremorizer`` is published and hosted as a Conda package on the
``fremor`` is published and hosted as a Conda package on the
`NOAA-GFDL conda channel <https://anaconda.org/NOAA-GFDL>`_. On pushes to the ``main`` branch, the
package is automatically updated using the workflow defined in ``.github/workflows/publish_conda.yml``,
which is equivalent to ``.github/workflows/build_conda.yml`` with an extra ``conda publish`` step.
Expand Down Expand Up @@ -157,7 +157,7 @@ a merge.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Avoid calling ``logging.basicConfig`` to re-configure logging behavior **outside** of
``fremorizer/__init__.py``. This creates another ``logging.handler`` without resolving the ambiguity
``fremor/__init__.py``. This creates another ``logging.handler`` without resolving the ambiguity
to previously defined loggers about which handler to use. If left in a PR at merge-time, this can cause
oddly silent logging behavior that is very tricky to debug.

Expand Down Expand Up @@ -188,7 +188,7 @@ instances, use the following pattern to safely ``chdir`` and ``chdir`` back:
---------------

In the case where non-Python files like templates, examples, and outputs are to be included in the
``fremorizer`` package, ``MANIFEST.in`` can provide the solution. Ensure the file exists within the
``fremor`` package, ``MANIFEST.in`` can provide the solution. Ensure the file exists within the
correct folder and add a line such as ``include fremor/fileName.fileExtension``.

For more efficiency, if there are multiple files of the same type needed, use something like
Expand Down
22 changes: 11 additions & 11 deletions docs/contributing_to_docs.rst
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
``fremorizer``'s documentation is built with ``sphinx`` and written in reStructuredText.
``fremor``'s documentation is built with ``sphinx`` and written in reStructuredText.
A decent cheat-sheet for reStructuredText can be found
`at this gist <https://gist.github.com/SMotaal/24006b13b354e6edad0c486749171a70#sections>`__.


With a PR to ilaflott/fremorizer (recommended)
With a PR to ilaflott/fremor (recommended)
----------------------------------------------

This approach is the easiest and most automated option for open-source contributors. It is completely
appropriate for casual editing of the docs and previewing the changes.

* Make a branch, either with ``ilaflott/fremorizer`` as the remote, or your own fork.
* Make a branch, either with ``ilaflott/fremor`` as the remote, or your own fork.
* Edit a file any non-zero amount, commit that change to your branch, and push. If the branch is
identical to ``main``, you cannot open a PR.
* Once the PR is opened, a ``readthedocs`` workflow will be run, even if that PR is in draft mode.
To confirm it is running (or did run), open your PR in a web browser, scroll to the bottom to find
the latest workflow runs under "checks", and click the ``readthedocs`` workflow.
* If the doc build is successful, you should see the ``fremorizer`` documentation page. If unsuccessful,
* If the doc build is successful, you should see the ``fremor`` documentation page. If unsuccessful,
you should see a ``404`` error.
* To review documentation differences, use the "Show diff" checkbox, which gives an explicit visual
difference highlight right on the built webpage.
Expand All @@ -30,7 +30,7 @@ This approach is good for deep debugging of the documentation build.
Lightweight Approach (recommended for docs-only)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you only need to build documentation and don't need the full ``fremorizer`` environment,
If you only need to build documentation and don't need the full ``fremor`` environment,
you can use a minimal setup. This approach uses ``autodoc_mock_imports`` in ``docs/conf.py``
to mock heavy dependencies like ``netCDF4``, ``cmor``, ``xarray``, etc.

Expand All @@ -39,14 +39,14 @@ From the root directory of your local repository copy:
.. code-block:: bash

# Create a lightweight docs-only environment
conda create -n fremorizer-docs python=3.11 -y
conda activate fremorizer-docs
conda create -n fremor-docs python=3.11 -y
conda activate fremor-docs

# Install minimal dependencies
pip install sphinx renku-sphinx-theme sphinx-rtd-theme click pyyaml jsonschema

# Generate API docs and build
sphinx-apidoc --ext-autodoc --output-dir docs fremorizer/ --separate
sphinx-apidoc --ext-autodoc --output-dir docs fremor/ --separate
sphinx-build docs docs/build

This will produce warnings about missing imports from test modules, but the build will succeed.
Expand All @@ -56,13 +56,13 @@ To view the result, open ``docs/build/index.html`` in your browser.
Full Environment Approach
~~~~~~~~~~~~~~~~~~~~~~~~~

If you are also developing and testing ``fremorizer`` functionality, set up a full conda environment:
If you are also developing and testing ``fremor`` functionality, set up a full conda environment:

.. code-block:: bash

# Create the full environment
conda env create -f environment.yaml
conda activate fremorizer
conda activate fremor

# Install in editable mode
pip install -e .
Expand All @@ -71,7 +71,7 @@ If you are also developing and testing ``fremorizer`` functionality, set up a fu
pip install sphinx renku-sphinx-theme sphinx-rtd-theme rstcheck

# Generate API docs and build
sphinx-apidoc --ext-autodoc --output-dir docs fremorizer/ --separate
sphinx-apidoc --ext-autodoc --output-dir docs fremor/ --separate
sphinx-build docs docs/build

Then open ``docs/build/index.html`` with your favorite web browser. You should be able to click around
Expand Down
2 changes: 1 addition & 1 deletion docs/cookbook.rst
Original file line number Diff line number Diff line change
Expand Up @@ -267,7 +267,7 @@ Common Issues and Solutions

The ``fremor yaml`` subcommand optionally relies on ``fre-cli``\'s ``yamltools`` module for
YAML consolidation. If ``fre-cli`` is not installed, you can use
``fremorizer``\'s native YAML loader with a single pre-consolidated YAML file.
``fremor``\'s native YAML loader with a single pre-consolidated YAML file.

To debug this issue:

Expand Down
4 changes: 2 additions & 2 deletions docs/index.rst
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. fremorizer documentation master file
.. fremor documentation master file

==============
``fremorizer``
``fremor``
==============

.. toctree::
Expand Down
Loading
Loading