From 5af7c333a6e59ae8ecc96d81f290ba3c09e06a75 Mon Sep 17 00:00:00 2001 From: neuronflow <7048826+neuronflow@users.noreply.github.com> Date: Fri, 1 Nov 2024 20:57:46 +0100 Subject: [PATCH] Initial commit --- .github/workflows/autoformat.yml | 9 ++ .github/workflows/pr-lint.yml | 10 ++ .github/workflows/release.yml | 30 ++++++ .github/workflows/tests.yml | 49 ++++++++++ .gitignore | 160 +++++++++++++++++++++++++++++++ .readthedocs.yaml | 20 ++++ CONTRIBUTING.md | 22 +++++ README.md | 52 ++++++++++ docs/.gitignore | 0 docs/Makefile | 20 ++++ docs/make.bat | 35 +++++++ docs/source/conf.py | 49 ++++++++++ docs/source/index.rst | 22 +++++ docs/source/preprocess_readme.py | 36 +++++++ docs/source/readme.rst | 6 ++ package_name/.gitignore | 0 pyproject.toml | 38 ++++++++ tests/__init__.py | 0 18 files changed, 558 insertions(+) create mode 100644 .github/workflows/autoformat.yml create mode 100644 .github/workflows/pr-lint.yml create mode 100644 .github/workflows/release.yml create mode 100644 .github/workflows/tests.yml create mode 100644 .gitignore create mode 100644 .readthedocs.yaml create mode 100644 CONTRIBUTING.md create mode 100644 README.md create mode 100644 docs/.gitignore create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/preprocess_readme.py create mode 100644 docs/source/readme.rst create mode 100644 package_name/.gitignore create mode 100644 pyproject.toml create mode 100644 tests/__init__.py diff --git a/.github/workflows/autoformat.yml b/.github/workflows/autoformat.yml new file mode 100644 index 0000000..314f2f4 --- /dev/null +++ b/.github/workflows/autoformat.yml @@ -0,0 +1,9 @@ +name: autoformat + +on: + issue_comment: + types: [created, edited] +jobs: + run_autoformat: + uses: BrainLesion/BrainLes/.github/workflows/autoformat.yml@main + secrets: inherit diff --git a/.github/workflows/pr-lint.yml b/.github/workflows/pr-lint.yml new file mode 100644 index 0000000..e0d4507 --- /dev/null +++ b/.github/workflows/pr-lint.yml @@ -0,0 +1,10 @@ +name: lint + +on: + pull_request: + branches: + - main +jobs: + run_lint: + uses: BrainLesion/BrainLes/.github/workflows/pr_lint.yml@main + secrets: inherit diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..7ad5450 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,30 @@ +name: release + +on: + release: + types: [created] + workflow_dispatch: + +jobs: + publish: + name: Publish to test PyPI + runs-on: ubuntu-latest + steps: + - name: Checkout Repository + uses: actions/checkout@v3 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: "3.x" + - name: Install dependencies + run: | + pip install build + pip install twine + - name: Build package + run: python -m build + - name: Upload to PyPI + env: + TWINE_USERNAME: __token__ + TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} + run: | + twine upload dist/*.whl diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 0000000..c5f097f --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,49 @@ +# This workflow will install Python dependencies, run tests and lint with a variety of Python versions +# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python + +name: tests + +on: + push: + branches: ["main"] + pull_request: + branches: ["main"] + +jobs: + build: + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest] #, windows-latest, macos-latest] # Extend to your needs + python-version: ["3.9", "3.10", "3.11", "3.12"] # Extend to your needs + + steps: + - uses: actions/checkout@v4 + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + cache: "pip" # caching pip dependencies + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install poetry + python -m poetry install + - name: Lint with flake8 + run: | + # stop the build if there are Python syntax errors or undefined names + python -m poetry run flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics + # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide + python -m poetry run flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics + # TODO adapt package_name to the name of your package + - name: Test with pytest + run: | + python -m poetry run pytest --cov package_name + # Add the following block to upload coverage to Codecov, requires a CODECOV_TOKEN secret to be set in the repository + # - name: Upload results to Codecov + # # Only upload to Codecov after a merge to the main branch + # if: github.ref == 'refs/heads/main' && github.event_name == 'push' + # uses: codecov/codecov-action@v4 + # with: + # token: ${{ secrets.CODECOV_TOKEN }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..68bc17f --- /dev/null +++ b/.gitignore @@ -0,0 +1,160 @@ +# 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/#use-with-ide +.pdm.toml + +# 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/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..f4e5e39 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,20 @@ +version: 2 + +build: + os: "ubuntu-22.04" + tools: + python: "3.10" + jobs: + post_create_environment: + # Install poetry + # https://python-poetry.org/docs/#installing-manually + - pip install poetry + post_install: + # Install dependencies with 'docs' dependency group + # https://python-poetry.org/docs/managing-dependencies/#dependency-groups + # VIRTUAL_ENV needs to be set manually for now. + # See https://github.com/readthedocs/readthedocs.org/pull/11152/ + - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs + +sphinx: + configuration: docs/source/conf.py \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6c5b2c2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,22 @@ +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) + +# Contributing + +First off, thanks for taking the time to contribute! 🎉 + + +## Contribute Code +Fork the repository, clone it and implement your contribution. + +**Setup:** +- We use [poetry](https://python-poetry.org/), make sure it is installed: `pip install poetry` +- Install dependencies by running: `poetry install` + +**Requirements:** +- Our project follows the [black code style](https://github.com/psf/black). Make sure your code is formatted accordingly. +- Please add _meaningful_ docstring for your functions and annotate types +- Please add _meaningful_ tests for your contribution in `/tests` and make sure _all_ tests are passing by running `python -m pytest` + + + +Once done, create a Pull Request to integrate the code into our project! diff --git a/README.md b/README.md new file mode 100644 index 0000000..5857420 --- /dev/null +++ b/README.md @@ -0,0 +1,52 @@ +# PACKAGE_NAME + +[![Python Versions](https://img.shields.io/pypi/pyversions/PACKAGE_NAME)](https://pypi.org/project/PACKAGE_NAME/) +[![Stable Version](https://img.shields.io/pypi/v/PACKAGE_NAME?label=stable)](https://pypi.python.org/pypi/PACKAGE_NAME/) +[![Documentation Status](https://readthedocs.org/projects/PACKAGE_NAME/badge/?version=latest)](http://PACKAGE_NAME.readthedocs.io/?badge=latest) +[![tests](https://github.com/BrainLesion/PACKAGE_NAME/actions/workflows/tests.yml/badge.svg)](https://github.com/BrainLesion/PACKAGE_NAME/actions/workflows/tests.yml) +[![codecov](https://codecov.io/gh/BrainLesion/PACKAGE_NAME/graph/badge.svg?token=A7FWUKO9Y4)](https://codecov.io/gh/BrainLesion/PACKAGE_NAME) +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) + +Description +## Features + + +## Installation + +With a Python 3.8+ environment, you can install `PACKAGE_NAME` directly from [PyPI](https://pypi.org/project/brats/): + +```bash +pip install PACKAGE_NAME +``` + + +## Use Cases and Tutorials + +A minimal example to create a segmentation could look like this: + +```python + # example +``` + + + + +## Citation + +If you use PACKAGE_NAME in your research, please cite it to support the development! + +``` +TODO: citation will be added asap +``` + +## Contributing + +We welcome all kinds of contributions from the community! + +### Reporting Bugs, Feature Requests and Questions + +Please open a new issue [here](https://github.com/BrainLesion/PACKAGE_NAME/issues). + +### Code contributions + +Nice to have you on board! Please have a look at our [CONTRIBUTING.md](CONTRIBUTING.md) file. diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..e69de29 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /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 = source +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/make.bat b/docs/make.bat new file mode 100644 index 0000000..747ffb7 --- /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=source +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/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..7bc126f --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,49 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import os +import sys +from subprocess import run + + +sys.path.insert(0, os.path.abspath("../../")) + + +run(["python", "preprocess_readme.py"]) + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "PACKAGE_NAME" +copyright = "2024, Marcel Rosier et al." +author = "Marcel Rosier, Florian Kofler" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", + "sphinx_copybutton", + "myst_parser", +] + +templates_path = ["_templates"] +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "furo" +# html_static_path = ["_static"] + +autodoc_default_options = { + "members": True, + "undoc-members": True, + "private-members": False, + "show-inheritance": True, +} diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..ee56e5b --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,22 @@ +PACKAGE_NAME documentation +=================== + +.. include:: ../README_preprocessed.md + :parser: myst_parser.sphinx_ + + +Sections +=================== + + + +.. toctree:: + :maxdepth: 1 + :caption: Getting Started: + + readme + +.. toctree:: + :maxdepth: 2 + :caption: API Reference: + diff --git a/docs/source/preprocess_readme.py b/docs/source/preprocess_readme.py new file mode 100644 index 0000000..da5cdb4 --- /dev/null +++ b/docs/source/preprocess_readme.py @@ -0,0 +1,36 @@ +import re + + +def preprocess_readme(input_file: str, output_file: str) -> None: + """Preprocess a README file to replace GitHub admonitions with Sphinx-style admonitions. + + Args: + input_file (str): original README file + output_file (str): processed README file + + """ + with open(input_file, "r") as file: + content = file.read() + + admonition_types = ["IMPORTANT", "NOTE", "TIP", "WARNING", "CAUTION"] + + for ad_type in admonition_types: + # Replace > [!ad_type] with Sphinx admonition syntax + content = re.sub( + r"> \[!" + + ad_type + + "\]\s*\n((?:> .*\n)*)", # Match the > [!ad_type] and subsequent lines + lambda m: "```{" + + ad_type + + "}\n" + + m.group(1).replace("> ", "").strip() + + "\n```", # Replace with MyST syntax + content, + ) + # Write the transformed content to the output file + with open(output_file, "w") as file: + file.write(content) + + +if __name__ == "__main__": + preprocess_readme("../../README.md", "../README_preprocessed.md") diff --git a/docs/source/readme.rst b/docs/source/readme.rst new file mode 100644 index 0000000..bf35448 --- /dev/null +++ b/docs/source/readme.rst @@ -0,0 +1,6 @@ +Readme +============== + + +.. include:: ../README_preprocessed.md + :parser: myst_parser.sphinx_ \ No newline at end of file diff --git a/package_name/.gitignore b/package_name/.gitignore new file mode 100644 index 0000000..e69de29 diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..c086d3d --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,38 @@ +[build-system] +requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"] +build-backend = "poetry_dynamic_versioning.backend" + +[tool.poetry-dynamic-versioning] +enable = true + +[tool.poetry] +name = "package_name" +version = "0.0.0" +description = "" +authors = ["Florian Kofler "] +repository = "https://www.TODO.com" +homepage = "https://www.TODO.com" +documentation = "https://www.TODO.com" +readme = "README.md" + + +# Add the exclude field directly under [tool.poetry] +exclude = ["examples", "benchmark"] + +[tool.poetry.dependencies] +python = ">=3.9" + + +[tool.poetry.dev-dependencies] +pytest = ">=8.0.0" +pytest-cov = ">=5.0.0" +flake8 = ">=4.0.1" + +[tool.poetry.group.docs] +optional = true + +[tool.poetry.group.docs.dependencies] +Sphinx = ">=7.0.0" +sphinx-copybutton = ">=0.5.2" +furo = ">=2024.8.6" +myst-parser = ">=2.0.0" diff --git a/tests/__init__.py b/tests/__init__.py new file mode 100644 index 0000000..e69de29