Developer Guide#

Setting Up Your Development Environment#

For developers of pyDARTdiags, we recommend installing pyDARTdiags as a local project in “editable” mode. This allows you to make changes to the code and see the changes reflected in your environment without having to reinstall the package.

To set up your development environment, follow these steps:

1. Create a Virtual Environment:

   python3 -m venv py-dart
   source py-dart/bin/activate
   

2. Clone the Repository:

   git clone https://github.com/NCAR/pyDARTdiags.git
   cd pyDARTdiags
   

3. Install Dependencies:

   pip install -r docs/requirements.txt
   

4. Install the Package in Editable Mode:

   pip install -e .
   

pyDARTdiags is now installed in your virtual environment in editable mode.

Building the Documentation Locally#

The documentation is built using Sphinx, is written in rst or MyST, and can be found in the docs directory. The API guide is built directly from docstrings in the python code, using Sphinx autodoc.

You can build the documentation with the following commands:

cd docs
make html

The built documentation will be in the build/html directory. Open the index.html file in your browser to view the documentation.

You can check all the links in the documentation by running the following command:

make linkcheck

Creating Examples#

We use Sphinx-Gallery to create examples for the documentation. The examples are in the pyDARTdiags/examples directory. To create a new example, create a new Python file called plot_example_name.py in the appropriate subdirectory. The example will be run when the documentation is built. For details on structuring your Sphinx-Gallery files take a look at the Sphinx-Gallery syntax.

Linting your code#

We use black for code formatting. Black will change your code to conform to the black style guide. To run black on the pyDARTdiags code, run the following command at the root of the repository:

black src/pydartdiags

Black is run on pull requests to ensure that the code is formatted correctly.

Writing Tests#

We use pytest for testing. Tests are in the test directory. The test/data directory is used to store small files used for testing. It is not for storing large files.

pyDARTdiags/
            ├── docs/
            ├── src/
            ├── tests/
                      ├── data/

To run the tests, you can use the following command:

pytest tests

Code Coverage#

We use Codecov to measure the percentage of code covered by tests. You can view the code coverage reports for the project at Codecov for pyDARTdiags. Code coverage for the test can be calculated locally using the pytest-cov package.

To create the coverage report, run the following command in the root directory:

pytest --cov=src tests

The coverage report will be displayed in the terminal.

To create a coverage report in HTML format, run the following command:

pytest --cov=src --cov-report=html