From 50d376d5afdd5e0b6d4a467cb0d95bde68475a63 Mon Sep 17 00:00:00 2001 From: jellepoland <65337813+jellepoland@users.noreply.github.com> Date: Fri, 16 Aug 2024 09:27:37 +0200 Subject: [PATCH] Initial commit --- .github/workflows/docs.yml | 29 ++++++ .github/workflows/tests.yml | 36 ++++++++ .gitignore | 168 +++++++++++++++++++++++++++++++++++ CITATION.cff | 30 +++++++ LICENSE | 21 +++++ README.md | 58 ++++++++++++ README_dev.md | 61 +++++++++++++ data/.gitkeep | 0 docs/Makefile | 20 +++++ docs/conf.py | 78 ++++++++++++++++ docs/index.rst | 20 +++++ docs/make.bat | 35 ++++++++ processed_data/.gitkeep | 0 pyproject.toml | 110 +++++++++++++++++++++++ requirements.txt | 11 +++ results/.gitkeep | 0 scripts/.gitkeep | 0 src/package-name/__init__.py | 0 tests/conftest.py | 13 +++ 19 files changed, 690 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 .github/workflows/tests.yml create mode 100644 .gitignore create mode 100644 CITATION.cff create mode 100644 LICENSE create mode 100644 README.md create mode 100644 README_dev.md create mode 100644 data/.gitkeep create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat create mode 100644 processed_data/.gitkeep create mode 100644 pyproject.toml create mode 100644 requirements.txt create mode 100644 results/.gitkeep create mode 100644 scripts/.gitkeep create mode 100644 src/package-name/__init__.py create mode 100644 tests/conftest.py diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..c00b10e --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,29 @@ +name: documentation + +on: [push, pull_request, workflow_dispatch] + +permissions: + contents: write + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.10' + - name: Install dependencies + run: | + pip install -r requirements.txt + - name: Sphinx build + run: | + sphinx-build docs/ docs/_build/ + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v4 + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} + with: + publish_branch: gh-pages + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/_build/ + force_orphan: true \ No newline at end of file diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 0000000..648f614 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,36 @@ +name: Python package testing + +on: + push: + pull_request: + branches: [ "main", "develop" ] + workflow_dispatch: + +jobs: + test: + permissions: + contents: read + pull-requests: write + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - name: Set up Python 3.10 + uses: actions/setup-python@v5 + with: + python-version: "3.10" + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install . + python -m pip install pytest pytest-cov + - name: Test with pytest and calculate coverage + run: | + pytest --cov-report "xml:coverage.xml" --cov=. + - name: Create Coverage + if: ${{ github.event_name == 'pull_request' }} + uses: orgoro/coverage@v3.1 + with: + coverageFile: coverage.xml + token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..19720e9 --- /dev/null +++ b/.gitignore @@ -0,0 +1,168 @@ +# User defined files and folders +data/ +processed_data/ +results/ + + +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +#poetry.lock + +# pdm +# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. +#pdm.lock +# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it +# in version control. +# https://pdm.fming.dev/latest/usage/project/#working-with-version-control +.pdm.toml +.pdm-python +.pdm-build/ + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# PyCharm +# JetBrains specific template is maintained in a separate JetBrains.gitignore that can +# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore +# and can be added to the global gitignore or merged into this file. For a more nuclear +# option (not recommended) you can uncomment the following to ignore the entire idea folder. +#.idea/ diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 0000000..e823dc7 --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,30 @@ +cff-version: 1.2.0 +message: "If you are using this software, please cite it as shown below." +authors: + - + family-names: "Doe" + given-names: "Jane" + orcid: "https://orcid.org/9999-9999-9999-9999" +title: "Name of your software" +keywords: + - Wind Energy +version: 0.1.0 +doi: "11.1111/11111" +date-released: YYYY-MM-DD +license: MIT +url: "https://github.com/your_repo" +preferred-citation: + type: article + authors: + - family-names: "Doe" + given-names: "Jane" + orcid: "https://orcid.org/9999-9999-9999-9999" + doi: "11.1111/11111" + journal: "The title of the journal" + month: 12 + start: 19 # the first page number + end: 29 #the last page number + title: "Name of your submitted paper" + issue: 9 + volume: 2 + year: 2024 \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..00251ac --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 Airborne Wind Energy Research Group + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..568d80d --- /dev/null +++ b/README.md @@ -0,0 +1,58 @@ +# Description +Generic Python template for AWE Group + +## :gear: Installation + +### Dependencies + +- Sphinx Dependencies, see [requirements](requirements.txt) + +### User Installation +Use the package manager [pip](https://pip.pypa.io/en/stable/) to install foobar. + +```bash +pip install . +``` + +### Developer Installation +Use the package manager [pip](https://pip.pypa.io/en/stable/) to install foobar. + +```bash +pip install -e .[dev] +``` + +## :eyes: Usage + +```python +import foobar + +# returns 'words' +foobar.pluralize('word') + +# returns 'geese' +foobar.pluralize('goose') + +# returns 'phenomenon' +foobar.singularize('phenomena') +``` +## :wave: Contributing (optional) + +Pull requests are welcome. For major changes, please open an issue first +to discuss what you would like to change. + +Please make sure to update tests as appropriate. + +## :warning: License and Waiver + +Specify the license under which your software is distributed, and include the copyright notice: + +> Technische Universiteit Delft hereby disclaims all copyright interest in the program “NAME PROGRAM” (one line description of the content or function) written by the Author(s). +> +> Prof.dr. H.G.C. (Henri) Werij, Dean of Aerospace Engineering +> +> Copyright (c) [YEAR] [NAME SURNAME]. + +## :gem: Help and Documentation +[AWE Group | Developer Guide](https://awegroup.github.io/developer-guide/) + + diff --git a/README_dev.md b/README_dev.md new file mode 100644 index 0000000..e6e5b66 --- /dev/null +++ b/README_dev.md @@ -0,0 +1,61 @@ +# Introduction + +Hi! Welcome to this Python Template, this `README_dev.md` contains instructions on the intended usage of this python template. + +## Getting-Started +1. Copy the template into a new repository, and edit the name to your project name +2. On your pc (locally) create a folder for your code project +3. Open this folder with your favorite editor (e.g. VSCode) and within it create a new python venv +4. Clone the just created repository into this folder, i.e. run `git clone ???` +5. Make some changes, and create your first commit see: ... + +## Setting-Up the Project +- [ ] Update + +## Proposed-Workflow + +### Generic +- Work with a main, develop and feature branches +- Write user settings in a `.yaml` file +- Don't use any hardcode inside your source folder +- Write scripts that should be run inside notebooks +- The other folders should only contain functions or data + + +### Steps for implementing a new feature +1. Create an issue on GitHub +2. Create a branch from this issue and change the branch source to `develop` +3. Use provided cmds to checkout this branch locally +4. --- Implement your new feature--- +5. Verify nothing broke using pytest +``` + pytest +``` +7. git add, git commit (with # to current Issue number), git push +``` + git add . + git commit -m "# " + git push +``` +7. Create a pull-request, with `base:develop`, to merge this feature branch and close this issue +9. Update branch information locally using `git fetch --prune`, pull in new info `git pull origin develop` and delete branch locally using `git branch -d ` +``` + git fetch --prune + git pull --all + git checkout develop + git pull +``` +9. Once merged on the remote and locally, delete this feature branch on the remote (see pull-request) and locally using +``` + git branch -d +``` +10. Close issue + + +## Explanation of folders/files +- `.gitkeep` is placed such that the empty folder show on GitHub, without this file would be automatically ignored and the project structure would not be clear. Once other files are present inside this folder, this file can be deleted. +- The folders `data/`, `processed_data/`, and `results/` have been added to the `.gitignore` file, as they are expected to contain + - large files that should not be uploaded to GitHub + - confidential data that should not be uploaded to GitHub + - generated data that can be recreated + - generated results that can be recreated diff --git a/data/.gitkeep b/data/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..a58d2c6 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,78 @@ +# 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 +sys.path.insert(0, os.path.abspath('..')) + + +# -- Project information ----------------------------------------------------- + +project = "Project" +copyright = "year, name" +author = "name" + +# The full version, including alpha/beta/rc tags +release = "0.1.0" + +# -- General configuration --------------------------------------------------- + +# The master toctree document. +master_doc = "index" + + +# 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_parser", + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", + "sphinx_copybutton", + "sphinx.ext.viewcode", + "sphinx_tabs.tabs" +] + +myst_enable_extensions = [ + "linkify", +] + +# Napoleon settings +napoleon_google_docstring = True + +# This value contains a list of modules to be mocked up. +# autodoc_mock_imports = [] + +# 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. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- 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_rtd_theme" +html_theme = "sphinx_book_theme" +# html_theme = "pydata_sphinx_theme" + + +html_title = "title" + +# 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'] \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..2e543a0 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +.. your project documentation master file, created by + sphinx-quickstart on Wed Jun 12 14:01:49 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to your project's documentation! +======================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..954237b --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/processed_data/.gitkeep b/processed_data/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..8dcacb6 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,110 @@ +[project] + +name = "exampleproject" +# Define the name of your project here. This is mandatory. Once you publish your package for the first time, +# this name will be locked and associated with your project. It affects how users will +# install your package via pip, like so: + +# $ pip install exampleproject + +# Your project will be accessible at: https://pypi.org/project/exampleproject/ + +version = "0.1.0" +# Version numbers should conform to PEP 440, and are also mandatory (but they can be set dynamic) +# https://www.python.org/dev/peps/pep-0440/ + +description = "Short description of your project" +# Provide a short, one-line description of what your project does. This is known as the +# "Summary" metadata field: +# https://packaging.python.org/specifications/core-metadata/#summary + +readme = "README.md" +# Here, you can include a longer description which often mirrors your README file. +# This description will appear on PyPI when your project is published. +# This corresponds to the "Description" metadata field: +# https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#readme + +requires-python = ">=3.8" +# Indicate the versions of Python your project is compatible with. Unlike the +# 'Programming Language' classifiers, 'pip install' will verify this field +# and prevent installation if the Python version does not match. +# Check https://endoflife.date/python for Python versions that are still supported. + +license = {file = "LICENSE"} +# This specifies the license. +# It can be a text (e.g. license = {text = "MIT License"}) or a reference to a file with the license text as shown above. + +keywords = ["wind-energy", "simulation"] +# Keywords that describe your project. These assist users in discovering your project on PyPI searches. +# These should be a comma-separated list reflecting the nature or domain of the project. + +authors = [ + {name = "A. Doe", email = "author@tudelft.nl" } +] +# Information about the original authors of the project and their contact details. + +maintainers = [ + {name = "B. Smith", email = "maintainer@tudelft.nl" } +] +# Information about the current maintainers of the project and their contact details. + +# Classifiers help categorize the project on PyPI and aid in discoverability. +# For a full list of valid classifiers, see https://pypi.org/classifiers/ +classifiers = [ + # Indicate the development status of your project (maturity). Commonly, this is + # 3 - Alpha + # 4 - Beta + # 5 - Stable + #. 6 - Mature + "Development Status :: 3 - Alpha", + + # Target audience + "Intended Audience :: Developers", + "Topic :: Scientific/Engineering", + + # License type + "License :: OSI Approved :: MIT License", + + # Python versions your software supports. This is not checked by pip install, and is different from "requires-python". + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3 :: Only", +] + +# Dependencies needed by your project. These packages will be installed by pip when +# your project is installed. Ensure these are existing, valid packages. + +# For more on how this field compares to pip's requirements files, see: +# https://packaging.python.org/discussions/install-requires-vs-requirements/ +dependencies = [ + "numpy", + "pandas>=1.5.3", + "matplotlib>=3.7.1" +] + +# You can define additional groups of dependencies here (e.g., development dependencies). +# These can be installed using the "extras" feature of pip, like so: + +# $ pip install exampleproject[dev] + +# These are often referred to as "extras" and provide optional functionality. +[project.optional-dependencies] +dev = [ + "pytest", + "pytest-cov", + "black", + ] + +[project.urls] +"Homepage" = "https://github.com/awegroup" +"Source" = "https://github.com/awegroup/" + +# List of relevant URLs for your project. These are displayed on the left sidebar of your PyPI page. +# This can include links to the homepage, source code, changelog, funding, etc. + + +# This [project] example was adopted from https://github.com/pypa/sampleproject/blob/main/pyproject.toml \ No newline at end of file diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..b3c93ef --- /dev/null +++ b/requirements.txt @@ -0,0 +1,11 @@ +# Sphinx extensions +sphinx +sphinx-tabs +sphinx-copybutton +myst-parser +linkify-it-py + +# Sphinx themes +pydata-sphinx-theme +sphinx-book-theme +sphinx-rtd-theme \ No newline at end of file diff --git a/results/.gitkeep b/results/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/scripts/.gitkeep b/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/package-name/__init__.py b/src/package-name/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 0000000..54c4719 --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,13 @@ +import pytest + +def pytest_sessionfinish(session, exitstatus): + """Exit with 0 if no tests were collected. + + This hook is called after the entire test run is finished, and is used to + override the exit status of the test run. If no tests were collected, the + exit status is set to 0 (indicating success) instead of 5 (indicating no + tests were collected). Otherwise, the template repository test actionwould + be marked as failing even though no tests were run. + """ + if exitstatus == 5: # no tests collected + session.exitstatus = 0