For Developers¶
This page is a “how to” for developers.
Repo Structure¶
This repository is structured as follows:
.
├── AUTHORS.rst . . . . . . . . Authors who contributed to code
├── CHANGELOG.rst . . . . . . . Tagged/Released Version Change Log
├── CONTRIBUTING.rst . . . . . How to contribute to the project
├── Dockerfile . . . . . . . . Creates golfball app Docker image (portable)
├── Jenkinsfile . . . . . . . . Jenkins pipeline definition to test golfball
├── LICENSE . . . . . . . . . . license
├── Makefile . . . . . . . . . Developer shortcuts (with help!)
├── README.rst . . . . . . . . Repository top-level README
├── container_test.sh . . . . . script to test golfball with Jenkins
├── data . . . . . . . . . . . DRAG MODEL SOURCE DATA
│ ├── cd_table.h5 . . . . . . HDF5 table used by golfball
│ ├── dimpledSpheresDragData/ directory with source drag data in it
│ └── write_cd_h5.py . . . . script to generate HDF5 table for golfball
├── docs . . . . . . . . . . . PACKAGE DOCUMENTATION
│ ├── Makefile . . . . . . . Build Targets for documentation
│ ├── _static/ . . . . . . . directory w/ static content
│ ├── authors.rst . . . . . . include ../AUTHORS.rst
│ ├── changelog.rst . . . . . include ../CHANGELOG.rst
│ ├── conf.py . . . . . . . . Documentation Configuration
│ ├── contributing.rst . . . include ../CONTRIBUTING.rst
│ ├── developers.rst . . . . Documentation for Developers (this file)
│ ├── examples.rst . . . . . How to use golfball package
│ ├── figures/ . . . . . . . Documentation Figures
│ ├── index.html . . . . . . Redirect to _build/html/index.html
│ ├── index.rst . . . . . . . Top-level Documentation File
│ ├── install.rst . . . . . . Installation Documentation
│ ├── kudos.rst . . . . . . "Thanks" recognition
│ ├── license.rst . . . . . . include ../LICENSE
│ ├── modules.rst . . . . . . code modules (extracts docstrings from code)
│ ├── quickstart.rst . . . . How to get started quickly
│ └── requirements.txt . . . sphinx build requirements
├── golfball . . . . . . . . . GOLFBALL PYTHON PACKAGE
│ ├── __init__.py . . . . . . Python package init file
│ ├── __version__.py . . . . current tag/release
│ ├── cd_table.h5 . . . . . . data that gets installed by pip
│ ├── sim.py . . . . . . . . Golfball Simulation
│ ├── stdAtm76.py . . . . . . Standard 1976 Atmosphere model
│ ├── utils.py . . . . . . . utilities for testing
│ └── yaml2results.py . . . . convert sim output to Dakota results format
├── setup.py . . . . . . . . . PyPA/PyPI setuptools configuration
└── test . . . . . . . . . . . AUTOMATED TESTS FOR PYTEST
├── sim/ . . . . . . . . . golfball sim tests
├── stdAtm76/ . . . . . . . atmosphere model tests
└── uq_dakota/ . . . . . . Dakota execution tests
The above list was made by taking the output of:
$ tree -L 2 .
at the top level of this repository, and then annotating the descriptions manually in this file.
Using Makefiles¶
The bulk of development tasks are automated by Make targets in makefiles. All makefiles have a built-in “help” target, that is also the default. For example, in the top directory of this repository:
$ make
-------------------- Makefile Target List --------------------------
Package: golfball
Git branch: main
--------------------------------------------------------------------
help Display list of intended targets for user (DEFAULT)
test-all check style, coverage, and run tests.
test run tests quickly with the default Python
coverage-report generate code coverage report with pytest
pylint-report check style with pylint
install install the package to the active Python's site-packages
install-dev install the package for active development
uninstall uninstall the packge from the current environment
docs generate Sphinx HTML documentation, including API docs
clean remove all artifacts
clean-build remove build artifacts
clean-pyc remove Python bytecode and object artifacts
clean-test remove test reports, caches, and coverage artifacts
clean-docs remove documentation build
clean-dakota clean dakota run outputs
docker-build Build docker image, using cached layers
docker-build-nc Build docker image, WITHOUT cached layers
docker-run run golfball in container as one-shot
docker-run-it run docker image interactively
docker-test test golfball inside the container
docker-pull pull branch image from registry
docker-push push branch image to registry
docker-archive Create g-zipped tarball of image
--------------------------------------------------------------------
The list above are the makefile targets the developer can do in that directory, with a short description of what they do. For the specific commands, look in the Makefile itself.
Local Development¶
The golfball sim is written to be completely generic with no platform-dependent libraries. Therefore, if you have a local Python environment, you can use pip to install this module as an editable module as instructed by the installation documentation. If you want to not have pip auto-install the dependencies that golfball needs, see the installation instructions for which python packages you’ll need to install with your other package manager (e.g. conda).
Local Testing¶
Using the “test” make target will first ensure that the golfball package is installed as an editable package (you can make changes without needing to re- install) and then executes the full pytest suite, capturing data for a coverage report, and produces an HTML pytest report at reports/pytest/index.html. In general, all targets involved in testing the code put their human-readable outputs into the reports/ directory.
To get the coverage report, run the “coverage_report” make target, and it will produce an HTML report at reports/coverage/index.html.
To get a pylint report, run the “pylint_report” make target, and it will produce a pylint report as a text file at reports/pylint/pylint_report.txt.
Note that you may see skipped tests for the dakota tests if dakota is not installed in your system path. This is by design. If you want the dakota tests to execute, check your dakota installation and make sure the executable is available in your system path.
Building Documentation¶
To build the documentation for this project, just use the “docs” target of the makefile. The documentation is posted on GitHub Pages, and it hosts from the master branch.
Building the Docker App¶
To build an executable image of the golfball package and its required environment for portability across platforms, use the “docker-build” makefile target. This will first build the “environment” image, then the “application” image. The use cases for the two different images are as follows:
1. The environment image is used to build the environment once and speed up repeated building of the application image as Python code changes are made. It is also the image used by the Jenkins CI/CD workflow to automatically test the golfball code when changes are made in GitHub.
2. The application image is the environment image with golfball installed in it. This is the portable “batteries included” application that can be used in parallel computing.
Testing the Docker App¶
Use the “docker-test” make target to execute pytest inside the container to run the automated test suite in the container environment. The test result will be an HTML report written at reports/container/pytest/index.html.