diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index daed7bd8..f37a85d8 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -2,21 +2,21 @@ default_language_version: python: python3 repos: - repo: https://github.com/pycqa/isort - rev: 5.12.0 + rev: 5.13.2 hooks: - id: isort name: isort stages: [commit] - repo: https://github.com/psf/black - rev: 23.11.0 + rev: 23.12.0 hooks: - id: black name: black stages: [commit] - repo: https://github.com/pre-commit/mirrors-mypy - rev: 'v1.7.0' # Use the sha / tag you want to point at + rev: 'v1.7.1' # Use the sha / tag you want to point at hooks: - id: mypy entry: mypy --install-types --non-interactive --config-file .mypy.ini @@ -40,7 +40,7 @@ repos: - repo: https://github.com/charliermarsh/ruff-pre-commit - rev: v0.1.5 + rev: v0.1.8 hooks: - id: ruff args: [--fix] diff --git a/docs/_config.yml b/docs/_config.yml index c5f424cd..dd773284 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -42,6 +42,7 @@ html: use_issues_button: true use_repository_button: true use_edit_page_button: true + home_page_in_navbar: false intersphinx_mapping: pyton: https://docs.python.org/3.10 @@ -79,6 +80,32 @@ sphinx: - sphinxcontrib.bibtex config: html_theme: sphinx_book_theme + html_theme_options: + icon_links: [ + { + name: GitHub, + url: https://github.com/WISDEM/WOMBAT, + icon: fa-brands fa-github, + }, + { + name: PyPI version, + url: https://pypi.org/project/WOMBAT/, + icon: "https://img.shields.io/pypi/v/WOMBAT", + type: url, + }, + { + name: PyPI downloads, + url: https://pypi.org/project/WOMBAT/, + icon: "https://img.shields.io/pypi/dm/WOMBAT", + type: url, + }, + { + name: Launch Binder, + url: "https://mybinder.org/v2/gh/WISDEM/WOMBAT/main?filepath=examples", + icon: "https://mybinder.org/badge_logo.svg", + type: url, + }, + ] language: 'python' autoyaml_level: 3 autosummary_generate: true diff --git a/docs/_toc.yml b/docs/_toc.yml index 8204fe2e..3ee2af09 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -7,6 +7,7 @@ parts: - caption: Getting Started chapters: - file: install + - file: contributing - file: presentations - file: workshops/index sections: diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..12ef6995 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,278 @@ +# Contributor's Guide + +(contributing:getting-started)= +## Getting Started + +These contributing guidelines should be read by software developers wishing to contribute code or +documentation changes into WOMBAT, or to push changes upstream to the main WISDEM/WOMBAT repository. + +1. Create a fork of WOMBAT on GitHub +2. Clone your fork of the repository + + ```bash + git clone -b develop https://github.com//WOMBAT.git + ``` + +3. Move into the WOMBAT source code directory + + ```bash + cd WOMBAT/ + ``` + +4. Install WOMBAT in editable mode with the appropriate developer tools + + - ``".[dev]"`` is for the linting, autoformatting, testing, and code checking tools + - ``".[docs]"`` is for the documentation building tools. Ideally, developers should also be + contributing to the documentation, and therefore checking that the documentation builds locally. + + ```bash + pip install -e ".[dev,docs]" + ``` + +5. Turn on the automated linting and code checking tools. Pre-commit runs at the commit level, and + will only check files that have been modified and staged (e.g., `git add `). + + ```bash + pre-commit install + ``` + +## Keeping your fork in sync with WISDEM/WOMBAT + +The "main" WOMBAT repository is regularly updated with ongoing research at NREL and beyond. After +creating and cloning your fork from the previous section, you might be wondering how to keep it +up to date with the latest improvements. + +Please note that the below process may introduce merge conflicts with your work, and this does not +provide guidance about how to deal with those conflicts. Here is a good resource for working on +[merge conflicts](https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts) that will +inevitably arise in development work. + +1. Ensure you're in the WOMBAT folder. This may look different depending on your operating system. + + ```bash + cd /your/path/to/WOMBAT/ + ``` + +2. If you haven't already, add WISDEM/WOMBAT as the "upstream" location (or whichever naming + convention you prefer). + + ```bash + git remote add upstream https://github.com/WISDEM/WOMBAT.git + ``` + + To find the name you've given WISDEM/WOMBAT again, you can simply run the following to display + all the remote sources you're tracking. + + ```bash + git remote -v + ``` + +3. Fetch all the remote changes + + ```bash + git fetch --all + ``` + +4. Sync the upstream (WISDEM) changes + + ```bash + # If there was a new release this will need to be updated + git checkout main + git pull upstream main + + # Most common branch to bring up to speed + git checkout develop + git pull upstream develop + ``` + +5. Bring your feature branch up to date with the latest changes, assuming you started from the + develop branch. + + ```bash + git checkout feature/your_contribution + git merge develop + ``` + +## Issue Tracking + +New feature requests, changes, enhancements, non-methodology features, and bug reports can be filed +as new issues in the [Github.com issue tracker](https://github.com/WISDEM/WOMBAT/issues) at any time. +Please be sure to fully describe the issue. + +For other issues, please email rob.hammond@nrel.gov. + +### Issue Submission Checklist + +1. Does the issue already exist? + Yes: If you find your issue already exists, make relevant comments and add your + [reaction](https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments). + Use a reaction in place of a "+1" comment: + + - 👍 - upvote + - 👎 - downvote + +2. Is this an individual bug report or feature request? +3. Can the bug be easily reproduced? + 1. Be sure to include enough details about your setup and the issue you've encountered + 2. Simplify as much of the code as possible to better isolate the problem +4. Will someone else understand the issue or change requested given the information provided? + +## Repository + +The WOMBAT repository is hosted on Github, and located here: http://github.com/WISDEM/WOMBAT + +This repository is organized using a modified git-flow system. Branches are organized as follows: + +- main: Stable release version. Must have good test coverage and may not have all the newest features. +- develop: Development branch which contains the newest features. Tests must pass, but code may be + unstable. +- feature/xxx: Feature ranch from develop, should reference a GitHub issue number. +- fix/xxx: Bug fix branch from develop, should reference a GitHub issue number. Can be based off + main if this is a necessary patch. + +To work on a feature, please fork WOMBAT first and then create a feature branch in your own fork. +Work out of this feature branch before submitting a pull request. + +Be sure to periodically synchronize the upstream develop branch into your feature branch to avoid +conflicts in the pull request. + +When your branch is ready, make a pull request to WISDEM/WOMBAT through the +[GitHub web interface](https://github.com/WISDEM/WOMBATpulls). + +## Coding Style + +This code uses a ``pre-commit`` workflow where code styling and linting is taken care of when a user +commits their code. Specifically, this code utilizes ``black`` for automatic formatting (line +length, quotation usage, hanging lines, etc.), ``isort`` for automatic import sorting, ``mypy`` +for typing, and ``ruff`` for linting. + +To activate the ``pre-commit`` workflow, the user must install the developer version as outlined in +the [getting started section](contributing:getting-started), and run the following line: + +```bash +pre-commit install +``` + +## Documentation + +Documentation is written primarily using Markdown, with some components written in +ReStructured Text, and is located in the `WOMBAT/docs/` directory. Additionally, all method and class +documentation is written as NumPy-style docstrings in the code itself, with some aspects documented +inline as needed. + +If the `docs` extras haven't already been installed, be sure to do so before you attempt to build +the documentation site. + +```bash +# Navigate to the top level directory of the repository +cd WOMBAT/ + +# Install the additional dependencies +pip install -e ".[docs]" +``` + +Now, run the build command as follows. + +```bash +# Build the docs +jupyter-book build docs +``` + +## Testing + +All code should be paired with a corresponding unit, regression, or integration test written with +the pytest framework. + +To run the tests you can use any of the following commands, depending on your needs. + +1. All the tests and check for test coverage: + + ```bash + pytest --cov=WOMBAT + ``` + +2. All the tests: + + ```bash + pytest + ``` + +(contributing:pull-request)= +## Pull Request + +Pull requests must be made for all changes. Most pull requests should be made against the develop +branch unless patching a bug that needs to be addressed immediately, and only core developers should +make pull requests to the main branch. + +All pull requests, regardless of the base branch, must include updated documentation and pass all +tests. In addition, code coverage should not be significantly negatively affected. + +### Scope + +Encapsulate the changes of one issue, or multiple if they are highly related. Three small pull +requests is greatly preferred over one large pull request. Not only will the review process be +shorter, but the review will be more focused and of higher quality, benefitting the author and code +base. Be sure to write a complete description of these changes in the pull request body. + +### Tests + +All tests must pass. Pull requests will be rejected or have changes requested if tests do not pass, +or cannot pass with changes. Tests are automatically run through Github Actions for any pull request +or push to the main or develop branches, but should also be run locally before submission. + +#### Test Coverage + +The testing framework described below will generate a coverage report from the tests run through +GitHub Actions. Please ensure that your work is fully covered by running them locally with the +coverage report enabled. + +### Documentation + +Include any relevant changes to inline documentation, docstrings, and any of the documentation files +located in `WOMBAT/docs/`. Pull requests will not be accepted until these changes are complete. + +Be sure to build the documentation and run the examples in the CLI locally prior to submission. + +### Changelog + +All changes must be documented appropriately in CHANGELOG.md in the [Unreleased] section. + +## Release Process + +This section is a reference for WOMBAT's maintainers to keep processes largely consistent +over time, regardless of who the core developers are. + +1. Bump version number and metadata in `WOMBAT/__init__.py` +2. Bump version numbers of any dependencies in `setup.py`. Be sure to separate to keep dependencies + separated by what they are required for (see the `project.optional-dependencies` section of + `pyproject.toml`) +3. Update the changelog at `WOMBAT/CHANGELOG.md`, changing the "UNRELEASED" section to the new + version and the release date (e.g. "[2.3 - 2022-01-18]"). +4. Make a pull request into develop with these updates, and be sure to follow the guide in + [Pull Requests](contributing:pull-request). + +5. Merge develop into main through the git command line + + ```bash + git checkout main + git merge develop + git push + ``` + +- Tag the new release version: + + ```bash + git tag -a v1.2.3 -m "Tag message for v1.2.3" + git push origin v1.2.3 + ``` + + The above process will trigger the `.github/workflows/python-publish-test.yml` GitHub Action + that builds the package and pushes it to Test PyPI. If this is successful, you can move to the + next step, otherwise the errors from the action should be addressed, and the tag should be + deleted, then recreated after the fix is published. + +- Deploying a Package to PyPi + - The repository is equipped with a GitHub Action to build and publish new versions to PyPI. A + maintainer can invoke this workflow by creating a new release on GitHub that corresponds to the + created tag in the previous step. + - The action is defined in `.github/workflows/python-publish.yml`. diff --git a/docs/index.rst b/docs/index.md similarity index 69% rename from docs/index.rst rename to docs/index.md index a9065b86..ba76eeb7 100644 --- a/docs/index.rst +++ b/docs/index.md @@ -1,35 +1,18 @@ -WOMBAT - Windfarm Operations and Maintenance cost-Benefit Analysis Tool -======================================================================= +# WOMBAT - Windfarm Operations and Maintenance cost-Benefit Analysis Tool -.. image:: https://img.shields.io/badge/DOI-10.2172%2F1894867-brightgreen?link=https://doi.org/10.2172/1894867 - :target: https://www.osti.gov/biblio/1894867 +[![DOI](https://img.shields.io/badge/DOI-10.2172%2F1894867-brightgreen?link=https://doi.org/10.2172/1894867)](https://www.osti.gov/biblio/1894867) +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) +[![PyPI Version](https://badge.fury.io/py/wombat.svg)](https://badge.fury.io/py/wombat) +[![PyPI downloads](https://img.shields.io/pypi/dm/wombat?link=https%3A%2F%2Fpypi.org%2Fproject%2FWOMBAT%2F)](https://pypi.org/project/WOMBAT/) -.. image:: https://badge.fury.io/py/wombat.svg - :target: https://badge.fury.io/py/wombat +[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/WISDEM/WOMBAT/main?filepath=examples) +[![Documentation site](https://jupyterbook.org/badge.svg)](https://wisdem.github.io/WOMBAT) -.. image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg - :target: https://opensource.org/licenses/Apache-2.0 +[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit) +[![Black formatter](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) +[![isort import formatter](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/) -.. image:: https://mybinder.org/badge_logo.svg - :target: https://mybinder.org/v2/gh/WISDEM/WOMBAT/main?filepath=examples - -.. image:: https://jupyterbook.org/badge.svg - :target: https://wisdem.github.io/WOMBAT - -.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white - :target: https://github.com/pre-commit/pre-commit - :alt: pre-commit - -.. image:: https://img.shields.io/badge/code%20style-black-000000.svg - :target: https://github.com/psf/black - -.. image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336 - :target: https://pycqa.github.io/isort/ - - - -Overview --------- +## Overview The WOMBAT framework is designed to provide an open source tool adhering to FLOSS principles for the wind farm lifecycle research community. Specifically, WOMBAT is meant to serve as @@ -40,9 +23,9 @@ As a supplement to this documentation site, there is also an NREL Technical Repo goes through much of the design and implementation details available at: https://www.osti.gov/biblio/1894867. If you use this software, please cite it using the following BibTeX information, or in commonly used citation formats -`here `_. +[here](https://www.osti.gov/biblio/1894867). -.. code-block:: bibtex +```bibtex @techreport{hammond2022wombat, title = {Windfarm Operations and Maintenance cost-Benefit Analysis Tool (WOMBAT)}, @@ -54,12 +37,12 @@ following BibTeX information, or in commonly used citation formats month = {10}, institution = {National Renewable Energy Lab. (NREL)}, } +``` For any questions, feel free to open up an issue in the repository or email: rob.hammond@nrel.gov. -Latest Changes? ---------------- +## Latest Changes? As of v0.8, a series of bug fixes in the cable, subassembly, repair management, and servicing equipment models that ensure repairs can't happen twice under limited @@ -73,9 +56,7 @@ Please see the CHANGELOG for details! * On this site: https://wisdem.github.io/WOMBAT/changelog.html * On GitHub: https://github.com/WISDEM/WOMBAT/blob/main/CHANGELOG.md - -The Model in 30 Seconds Or Less -------------------------------- +## The Model in 30 Seconds Or Less In general, the model has 2 overarching branches: the wind farm itself (the technology strategy), and the simulation environment (the maintenance strategy). For the wind farm @@ -88,9 +69,7 @@ As for the environment, this is where the discrete event simulation itself happe addition to logging, repair logic, and other necessary modeling pieces. The image below provides a more visual representation of this description. - -High Level Architecture -^^^^^^^^^^^^^^^^^^^^^^^ +### High Level Architecture The code is largely broken up into two categories: the wind farm and objects contained within it, and the simulation and simulation environment components. The wind farm is @@ -99,13 +78,10 @@ composed of subassemblies (a conglomerate of components). For the simulation env we consider all the pieces that allow the simulation to happen such as the API, servicing equipment, repair manager to hold and pass on tasks, and results post-processing. -.. image:: images/high_level_diagram.svg - -The following section describes how a wind farm is simulated and the flow of events as -they occur within the model. +```{image} images/high_level_diagram.svg +``` -Simulation Architecture -^^^^^^^^^^^^^^^^^^^^^^^ +### Simulation Architecture In the diagram below, we demonstrate the lifecycle of the simulation through the lifecycle of a single failure. @@ -133,40 +109,14 @@ lifecycle of a single failure. will continue on in the same manner until it reaches its user- or weather-defined ending point. -.. image:: images/simulation_diagram.png - - -.. Welcome -.. ------- - -.. .. toctree:: -.. :maxdepth: 2 -.. :caption: Getting Started - -.. install -.. presentations -.. workshops/index -.. team - - - -.. Using WOMBAT -.. ------------ - -.. .. toctree:: -.. :maxdepth: 2 -.. :caption: Working with the code base - -.. examples/index -.. API/index -.. changelog - +```{image} images/simulation_diagram.svg +``` -License -------- +## License Notice on the NREL application of the Apache-2 license, also found on the -`GitHub `_, along with the -complete `license `_ details. +[GitHub](https://github.com/WISDEM/WOMBAT/blob/main/NOTICE), along with the +complete [license](https://github.com/WISDEM/WOMBAT/blob/main/LICENSE) details. -.. include:: ../NOTICE +```{include} ../NOTICE +``` diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index ac2cf6f5..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,139 +0,0 @@ -"""Configuration file for the Sphinx documentation builder.""" - - -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -import os -import sys - -import wombat - - -sys.path.insert(0, os.path.abspath("../..")) - - -# -- Project information ----------------------------------------------------- - -project = "WOMBAT" -copyright = "2021 Alliance for Sustainable Energy, LLC" -author = ( - "Rob Hammond," - " Aubryn Cooperman," - " Aaron Barker," - " Alicia Key," - " Matt Shields," - " Annika Eberle" -) - -# The full version, including alpha/beta/rc tags -release = wombat.__version__ - - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named "sphinx.ext.*") or your custom -# ones. -extensions = [ - "myst_nb", - "sphinx_book_theme", - "sphinx.ext.autodoc", - "sphinx.ext.coverage", - "sphinx.ext.napoleon", - "sphinx.ext.autosectionlabel", - "sphinxcontrib.bibtex", -] - -# Make sure the target is unique -autosectionlabel_prefix_document = True - -master_doc = "index" - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -nb_execution_excludepatterns = ["_build", "Thumbs.db", ".DS_Store"] - -bibtex_bibfiles = ["refs.bib"] - -intersphinx_mapping = { - "python": ("https://docs.python.org/3.10", None), - "sphinx": ("https://www.sphinx-doc.org/en/3.x", None), -} - -suppress_warnings = ["myst.domains"] - -myst_enable_extensions = [ - "dollarmath", - "amsmath", - "deflist", - # "html_admonition", - # "html_image", - "colon_fence", - # "smartquotes", - # "replacements", - "linkify", - # "substitution", -] -myst_url_schemes = ["http", "https", "mailto"] - -source_suffix = { - ".rst": "restructuredtext", - ".ipynb": "myst-nb", - ".myst": "myst-nb", -} - -# toggle this between auto/off to rerun full documentation build -nb_execution_mode = "auto" -nb_execution_timeout = -1 -nb_execution_allow_errors = True -nb_merge_streams = True -# nb_execution_excludepatterns.extend( -# [ -# "how_to.md", -# "metrics_demonstration.md", -# "strategy_demonstration.md", -# ] -# ) - -myst_heading_anchors = 3 - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_book_theme" -html_title = f"WOMBAT v{release}" -html_theme_options = { - "github_url": "https://github.com/WISDEM/WOMBAT", - "repository_url": "https://github.com/WISDEM/WOMBAT", - "repository_branch": "main", - "use_repository_button": True, - "use_issues_button": True, - "path_to_docs": "docs/", - "navigation_depth": 2, - "home_page_in_toc": True, - "show_toc_level": 2, -} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ["_static"] - -# Napoleon options -napoleon_google_docstring = False -napoleon_use_param = False -napoleon_use_ivar = True diff --git a/pyproject.toml b/pyproject.toml index 5ca757b0..b39fa347 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "wombat" -version = "0.9.2" +dynamic = ["version"] authors = [{name = "Rob Hammond", email = "rob.hammond@nrel.gov"}] readme = {file = "README.md", content-type = "text/markdown"} description = "Windfarm operations and maintenance cost-benefit analysis tool" @@ -104,7 +104,10 @@ include-package-data = true include = ["wombat", "library", "*.yaml", "*.csv"] exclude = ["*.tests", "*.tests.*", "tests.*", "tests"] -[coverage.run] +[tool.setuptools.dynamic] +version = {attr = "wombat.__version__"} + +[tool.coverage.run] # Coverage.py configuration file # https://coverage.readthedocs.io/en/latest/config.html branch = true diff --git a/wombat/__init__.py b/wombat/__init__.py index 844d56a2..56b27961 100644 --- a/wombat/__init__.py +++ b/wombat/__init__.py @@ -1,9 +1,7 @@ """Package initialization.""" -import importlib.metadata - from wombat.core import Metrics, Simulation from wombat.core.library import create_library_structure -__version__ = importlib.metadata.version("wombat") +__version__ = "0.9.2"