From 3caab39c1e16bb8002b6eed0aac9d8245ca3439b Mon Sep 17 00:00:00 2001 From: Steph Merritt Date: Mon, 29 Jan 2024 12:25:01 +0000 Subject: [PATCH 1/6] Applying LINCC Frameworks template. --- .copier-answers.yml | 17 ++++ .git_archival.txt | 4 + .gitattributes | 24 +++++ .github/pull_request_template.md | 63 +++++++++++++ .github/workflows/build-documentation.yml | 38 ++++++++ .github/workflows/linting.yml | 35 +++++++ .github/workflows/pre-commit-ci.yml | 34 +++++++ .github/workflows/publish-to-pypi.yml | 37 ++++++++ .github/workflows/smoke-test.yml | 43 +++++++++ .github/workflows/testing-and-coverage.yml | 37 ++++++++ .pre-commit-config.yaml | 104 +++++++++++++++++++++ .prepare_project.sh | 25 +++++ .readthedocs.yml | 22 +++++ README.md | 49 ++++++++++ docs/Makefile | 31 ++++++ docs/conf.py | 48 ++++++++++ docs/index.rst | 50 ++++++++++ docs/notebooks.rst | 6 ++ docs/notebooks/README.md | 1 + docs/notebooks/intro_notebook.ipynb | 82 ++++++++++++++++ docs/requirements.txt | 7 ++ pyproject.toml | 65 +++++++++++++ src/adler/__init__.py | 3 + src/adler/example_module.py | 23 +++++ tests/adler/conftest.py | 0 tests/adler/test_example_module.py | 13 +++ 26 files changed, 861 insertions(+) create mode 100644 .copier-answers.yml create mode 100644 .git_archival.txt create mode 100644 .gitattributes create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/build-documentation.yml create mode 100644 .github/workflows/linting.yml create mode 100644 .github/workflows/pre-commit-ci.yml create mode 100644 .github/workflows/publish-to-pypi.yml create mode 100644 .github/workflows/smoke-test.yml create mode 100644 .github/workflows/testing-and-coverage.yml create mode 100644 .pre-commit-config.yaml create mode 100644 .prepare_project.sh create mode 100644 .readthedocs.yml create mode 100644 README.md create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/notebooks.rst create mode 100644 docs/notebooks/README.md create mode 100644 docs/notebooks/intro_notebook.ipynb create mode 100644 docs/requirements.txt create mode 100644 pyproject.toml create mode 100644 src/adler/__init__.py create mode 100644 src/adler/example_module.py create mode 100644 tests/adler/conftest.py create mode 100644 tests/adler/test_example_module.py diff --git a/.copier-answers.yml b/.copier-answers.yml new file mode 100644 index 0000000..2124396 --- /dev/null +++ b/.copier-answers.yml @@ -0,0 +1,17 @@ +# Changes here will be overwritten by Copier +_commit: v1.4.6 +_src_path: gh:lincc-frameworks/python-project-template +author_email: s.merritt@qub.ac.uk +author_name: Adler Team +create_example_module: true +custom_install: true +include_benchmarks: false +include_docs: true +include_notebooks: true +mypy_type_checking: none +package_name: adler +preferred_linter: black +project_license: none +project_name: adler +project_organization: lsst-uk +use_isort: false diff --git a/.git_archival.txt b/.git_archival.txt new file mode 100644 index 0000000..b1a286b --- /dev/null +++ b/.git_archival.txt @@ -0,0 +1,4 @@ +node: $Format:%H$ +node-date: $Format:%cI$ +describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$ +ref-names: $Format:%D$ \ No newline at end of file diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..343a755 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,24 @@ +# For explanation of this file and uses see +# https://git-scm.com/docs/gitattributes +# https://developer.lsst.io/git/git-lfs.html#using-git-lfs-enabled-repositories +# https://lincc-ppt.readthedocs.io/en/latest/practices/git-lfs.html +# +# Used by https://github.com/lsst/afwdata.git +# *.boost filter=lfs diff=lfs merge=lfs -text +# *.dat filter=lfs diff=lfs merge=lfs -text +# *.fits filter=lfs diff=lfs merge=lfs -text +# *.gz filter=lfs diff=lfs merge=lfs -text +# +# apache parquet files +# *.parq filter=lfs diff=lfs merge=lfs -text +# +# sqlite files +# *.sqlite3 filter=lfs diff=lfs merge=lfs -text +# +# gzip files +# *.gz filter=lfs diff=lfs merge=lfs -text +# +# png image files +# *.png filter=lfs diff=lfs merge=lfs -text + +.git_archival.txt export-subst \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..76e043c --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,63 @@ + + +## Change Description + +- [ ] My PR includes a link to the issue that I am addressing + + + +## Solution Description + + + + +## Code Quality +- [ ] I have read the Contribution Guide +- [ ] My code follows the code style of this project +- [ ] My code builds (or compiles) cleanly without any errors or warnings +- [ ] My code contains relevant comments and necessary documentation + +## Project-Specific Pull Request Checklists + + +### Bug Fix Checklist +- [ ] My fix includes a new test that breaks as a result of the bug (if possible) +- [ ] My change includes a breaking change + - [ ] My change includes backwards compatibility and deprecation warnings (if possible) + +### New Feature Checklist +- [ ] I have added or updated the docstrings associated with my feature using the [NumPy docstring format](https://numpydoc.readthedocs.io/en/latest/format.html) +- [ ] I have updated the tutorial to highlight my new feature (if appropriate) +- [ ] I have added unit/End-to-End (E2E) test cases to cover my new feature +- [ ] My change includes a breaking change + - [ ] My change includes backwards compatibility and deprecation warnings (if possible) + +### Documentation Change Checklist +- [ ] Any updated docstrings use the [NumPy docstring format](https://numpydoc.readthedocs.io/en/latest/format.html) + +### Build/CI Change Checklist +- [ ] If required or optional dependencies have changed (including version numbers), I have updated the README to reflect this +- [ ] If this is a new CI setup, I have added the associated badge to the README + + + +### Other Change Checklist +- [ ] Any new or updated docstrings use the [NumPy docstring format](https://numpydoc.readthedocs.io/en/latest/format.html). +- [ ] I have updated the tutorial to highlight my new feature (if appropriate) +- [ ] I have added unit/End-to-End (E2E) test cases to cover any changes +- [ ] My change includes a breaking change + - [ ] My change includes backwards compatibility and deprecation warnings (if possible) diff --git a/.github/workflows/build-documentation.yml b/.github/workflows/build-documentation.yml new file mode 100644 index 0000000..35e5f72 --- /dev/null +++ b/.github/workflows/build-documentation.yml @@ -0,0 +1,38 @@ +# This workflow will install Python dependencies, build the package and then build the documentation. + +name: Build documentation + + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + build: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + - name: Set up Python 3.10 + uses: actions/setup-python@v4 + with: + python-version: '3.10' + - name: Install dependencies + run: | + sudo apt-get update + python -m pip install --upgrade pip + if [ -f docs/requirements.txt ]; then pip install -r docs/requirements.txt; fi + pip install . + - name: Install notebook requirements + run: | + sudo apt-get install pandoc + - name: Build docs + run: | + sphinx-build -T -E -b html -d docs/build/doctrees ./docs docs/build/html diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml new file mode 100644 index 0000000..37e1a3d --- /dev/null +++ b/.github/workflows/linting.yml @@ -0,0 +1,35 @@ +# This workflow will install Python dependencies, then perform static linting analysis. +# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions + +name: Lint + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' + - name: Install dependencies + run: | + sudo apt-get update + python -m pip install --upgrade pip + pip install . + pip install .[dev] + if [ -f requirements.txt ]; then pip install -r requirements.txt; fi + - name: Analyze code with linter + uses: psf/black@stable + with: + src: ./src diff --git a/.github/workflows/pre-commit-ci.yml b/.github/workflows/pre-commit-ci.yml new file mode 100644 index 0000000..8397877 --- /dev/null +++ b/.github/workflows/pre-commit-ci.yml @@ -0,0 +1,34 @@ +# This workflow runs pre-commit hooks on pull requests to enforce coding style. +# To ensure correct configuration, please refer to: +# https://lincc-ppt.readthedocs.io/en/latest/practices/ci_precommit.html + +name: Run pre-commit hooks + +on: + pull_request: + +jobs: + pre-commit-ci: + runs-on: ubuntu-latest + env: + SKIP: "check-lincc-frameworks-template-version,pytest-check,no-commit-to-branch,validate-pyproject,check-added-large-files,sphinx-build" + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' + - name: Install dependencies + run: | + sudo apt-get update + python -m pip install --upgrade pip + pip install . + pip install .[dev] + if [ -f requirements.txt ]; then pip install -r requirements.txt; fi + - uses: pre-commit/action@v3.0.0 + with: + extra_args: --from-ref ${{ github.event.pull_request.base.sha }} --to-ref ${{ github.event.pull_request.head.sha }} + - uses: pre-commit-ci/lite-action@v1.0.1 + if: always() \ No newline at end of file diff --git a/.github/workflows/publish-to-pypi.yml b/.github/workflows/publish-to-pypi.yml new file mode 100644 index 0000000..3147bde --- /dev/null +++ b/.github/workflows/publish-to-pypi.yml @@ -0,0 +1,37 @@ +# This workflow will upload a Python Package using Twine when a release is created +# For more information see: https://github.com/pypa/gh-action-pypi-publish#trusted-publishing + +# This workflow uses actions that are not certified by GitHub. +# They are provided by a third-party and are governed by +# separate terms of service, privacy policy, and support +# documentation. + +name: Upload Python Package + +on: + release: + types: [published] + +permissions: + contents: read + +jobs: + deploy: + + runs-on: ubuntu-latest + permissions: + id-token: write + steps: + - uses: actions/checkout@v3 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install build + - name: Build package + run: python -m build + - name: Publish package + uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/.github/workflows/smoke-test.yml b/.github/workflows/smoke-test.yml new file mode 100644 index 0000000..2aec838 --- /dev/null +++ b/.github/workflows/smoke-test.yml @@ -0,0 +1,43 @@ +# This workflow will run daily at 06:45. +# It will install Python dependencies and run tests with a variety of Python versions. +# See documentation for help debugging smoke test issues: +# https://lincc-ppt.readthedocs.io/en/latest/practices/ci_testing.html#version-culprit + +name: Unit test smoke test + +on: + + # Runs this workflow automatically + schedule: + - cron: 45 6 * * * + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +jobs: + build: + + runs-on: ubuntu-latest + strategy: + matrix: + python-version: ['3.8', '3.9', '3.10'] + + steps: + - uses: actions/checkout@v3 + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v4 + with: + python-version: ${{ matrix.python-version }} + - name: Install dependencies + run: | + sudo apt-get update + python -m pip install --upgrade pip + pip install . + pip install .[dev] + if [ -f requirements.txt ]; then pip install -r requirements.txt; fi + - name: List dependencies + run: | + pip list + - name: Run unit tests with pytest + run: | + python -m pytest tests diff --git a/.github/workflows/testing-and-coverage.yml b/.github/workflows/testing-and-coverage.yml new file mode 100644 index 0000000..3e67786 --- /dev/null +++ b/.github/workflows/testing-and-coverage.yml @@ -0,0 +1,37 @@ +# This workflow will install Python dependencies, run tests and report code coverage with a variety of Python versions +# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions + +name: Unit test and code coverage + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + build: + + runs-on: ubuntu-latest + strategy: + matrix: + python-version: ['3.8', '3.9', '3.10'] + + steps: + - uses: actions/checkout@v3 + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v4 + with: + python-version: ${{ matrix.python-version }} + - name: Install dependencies + run: | + sudo apt-get update + python -m pip install --upgrade pip + pip install . + pip install .[dev] + if [ -f requirements.txt ]; then pip install -r requirements.txt; fi + - name: Run unit tests with pytest + run: | + python -m pytest tests --cov=adler --cov-report=xml + - name: Upload coverage report to codecov + uses: codecov/codecov-action@v3 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..a5c887a --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,104 @@ +fail_fast: true +repos: + + # Compare the local template version to the latest remote template version + # This hook should always pass. It will print a message if the local version + # is out of date. + - repo: https://github.com/lincc-frameworks/pre-commit-hooks + rev: v0.1.1 + hooks: + - id: check-lincc-frameworks-template-version + name: Check template version + description: Compare current template version against latest + verbose: true + + # Clear output from jupyter notebooks so that only the input cells are committed. + - repo: local + hooks: + - id: jupyter-nb-clear-output + name: Clear output from Jupyter notebooks + description: Clear output from Jupyter notebooks. + files: \.ipynb$ + stages: [commit] + language: system + entry: jupyter nbconvert --clear-output + + # Prevents committing directly branches named 'main' and 'master'. + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + hooks: + - id: no-commit-to-branch + name: Prevent main branch commits + description: Prevent the user from committing directly to the primary branch. + - id: check-added-large-files + name: Check for large files + description: Prevent the user from committing very large files. + args: ['--maxkb=500'] + + # Verify that pyproject.toml is well formed + - repo: https://github.com/abravalheri/validate-pyproject + rev: v0.12.1 + hooks: + - id: validate-pyproject + name: Validate pyproject.toml + description: Verify that pyproject.toml adheres to the established schema. + + + + + # Analyze the code style and report code that doesn't adhere. + - repo: https://github.com/psf/black + rev: 23.7.0 + hooks: + - id: black-jupyter + name: Format code using black + types_or: [python, pyi, jupyter] + # It is recommended to specify the latest version of Python + # supported by your project here, or alternatively use + # pre-commit's default_language_version, see + # https://pre-commit.com/#top_level-default_language_version + language_version: python3.10 + + + + + # Run unit tests, verify that they pass. Note that coverage is run against + # the ./src directory here because that is what will be committed. In the + # github workflow script, the coverage is run against the installed package + # and uploaded to Codecov by calling pytest like so: + # `python -m pytest --cov= --cov-report=xml` + - repo: local + hooks: + - id: pytest-check + name: Run unit tests + description: Run unit tests with pytest. + entry: bash -c "if python -m pytest --co -qq; then python -m pytest --cov=./src --cov-report=html; fi" + language: system + pass_filenames: false + always_run: true + # Make sure Sphinx can build the documentation while explicitly omitting + # notebooks from the docs, so users don't have to wait through the execution + # of each notebook or each commit. By default, these will be checked in the + # GitHub workflows. + - repo: local + hooks: + - id: sphinx-build + name: Build documentation with Sphinx + entry: sphinx-build + language: system + always_run: true + exclude_types: [file, symlink] + args: + [ + "-M", # Run sphinx in make mode, so we can use -D flag later + # Note: -M requires next 3 args to be builder, source, output + "html", # Specify builder + "./docs", # Source directory of documents + "./_readthedocs", # Output directory for rendered documents + "-T", # Show full trace back on exception + "-E", # Don't use saved env; always read all files + "-d", # Flag for cached environment and doctrees + "./docs/_build/doctrees", # Directory + "-D", # Flag to override settings in conf.py + "exclude_patterns=notebooks/*", # Exclude our notebooks from pre-commit + ] diff --git a/.prepare_project.sh b/.prepare_project.sh new file mode 100644 index 0000000..17b1b5e --- /dev/null +++ b/.prepare_project.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash + +echo "Initializing local git repository" +{ + gitversion=( $(git version | sed 's/^.* //;s/\./ /g') ) + if let "${gitversion[0]}<2"; then + # manipulate directly + git init . && echo 'ref: refs/heads/main' >.git/HEAD + elif let "${gitversion[0]}==2 & ${gitversion[1]}<34"; then + # rename master to main + git init . && { git branch -m master main 2>/dev/null || true; }; + else + # set the initial branch name to main + git init --initial-branch=main >/dev/null + fi +} > /dev/null + +echo "Installing package and runtime dependencies in local environment" +pip install -e . > /dev/null + +echo "Installing developer dependencies in local environment" +pip install -e .'[dev]' > /dev/null + +echo "Installing pre-commit" +pre-commit install > /dev/null diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..79bfc27 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,22 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "3.10" + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/requirements.txt + - method: pip + path: . diff --git a/README.md b/README.md new file mode 100644 index 0000000..3ef1da4 --- /dev/null +++ b/README.md @@ -0,0 +1,49 @@ +# adler + +[![Template](https://img.shields.io/badge/Template-LINCC%20Frameworks%20Python%20Project%20Template-brightgreen)](https://lincc-ppt.readthedocs.io/en/latest/) + +[![PyPI](https://img.shields.io/pypi/v/adler?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/adler/) +[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/lsst-uk/adler/smoke-test.yml)](https://github.com/lsst-uk/adler/actions/workflows/smoke-test.yml) +[![codecov](https://codecov.io/gh/lsst-uk/adler/branch/main/graph/badge.svg)](https://codecov.io/gh/lsst-uk/adler) +[![Read the Docs](https://img.shields.io/readthedocs/adler)](https://adler.readthedocs.io/) + +This project was automatically generated using the LINCC-Frameworks +[python-project-template](https://github.com/lincc-frameworks/python-project-template). + +A repository badge was added to show that this project uses the python-project-template, however it's up to +you whether or not you'd like to display it! + +For more information about the project template see the +[documentation](https://lincc-ppt.readthedocs.io/en/latest/). + +## Dev Guide - Getting Started + +Before installing any dependencies or writing code, it's a great idea to create a +virtual environment. LINCC-Frameworks engineers primarily use `conda` to manage virtual +environments. If you have conda installed locally, you can run the following to +create and activate a new environment. + +``` +>> conda create env -n python=3.10 +>> conda activate +``` + +Once you have created a new environment, you can install this project for local +development using the following commands: + +``` +>> pip install -e .'[dev]' +>> pre-commit install +>> conda install pandoc +``` + +Notes: +1) The single quotes around `'[dev]'` may not be required for your operating system. +2) `pre-commit install` will initialize pre-commit for this local repository, so + that a set of tests will be run prior to completing a local commit. For more + information, see the Python Project Template documentation on + [pre-commit](https://lincc-ppt.readthedocs.io/en/latest/practices/precommit.html) +3) Install `pandoc` allows you to verify that automatic rendering of Jupyter notebooks + into documentation for ReadTheDocs works as expected. For more information, see + the Python Project Template documentation on + [Sphinx and Python Notebooks](https://lincc-ppt.readthedocs.io/en/latest/practices/sphinx.html#python-notebooks) diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..a5622f1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,31 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= -T -E -d _build/doctrees -D language=en +EXCLUDENB ?= -D exclude_patterns="notebooks/*","_build","**.ipynb_checkpoints" +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = ../_readthedocs/ + +.PHONY: help clean Makefile no-nb no-notebooks + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +# Build all Sphinx docs locally, except the notebooks +no-nb no-notebooks: + @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(EXCLUDENB) $(O) + +# Cleans up files generated by the build process +clean: + rm -r "_build/doctrees" + rm -r "$(BUILDDIR)" + +# 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..18c936d --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,48 @@ +# 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 importlib.metadata import version + +# Define path to the code to be documented **relative to where conf.py (this file) is kept** +sys.path.insert(0, os.path.abspath("../src/")) + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "adler" +copyright = "2023, Adler Team" +author = "Adler Team" +release = version("adler") +# for example take major/minor +version = ".".join(release.split(".")[:2]) + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["sphinx.ext.mathjax", "sphinx.ext.napoleon", "sphinx.ext.viewcode"] + +extensions.append("autoapi.extension") +extensions.append("nbsphinx") + +templates_path = [] +exclude_patterns = ["_build", "**.ipynb_checkpoints"] + +# This assumes that sphinx-build is called from the root directory +master_doc = "index" +# Remove 'view source code' from top of page (for html, not python) +html_show_sourcelink = False +# Remove namespaces from class/method signatures +add_module_names = False + +autoapi_type = "python" +autoapi_dirs = ["../src"] +autoapi_ignore = ["*/__main__.py", "*/_version.py"] +autoapi_add_toc_tree_entry = False +autoapi_member_order = "bysource" + +html_theme = "sphinx_rtd_theme" diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..ec57dc4 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,50 @@ +.. adler documentation main file. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to adler's documentation! +======================================================================================== + +Dev Guide - Getting Started +--------------------------- + +Before installing any dependencies or writing code, it's a great idea to create a +virtual environment. LINCC-Frameworks engineers primarily use `conda` to manage virtual +environments. If you have conda installed locally, you can run the following to +create and activate a new environment. + +.. code-block:: bash + + >> conda create env -n python=3.10 + >> conda activate + + +Once you have created a new environment, you can install this project for local +development using the following commands: + +.. code-block:: bash + + >> pip install -e .'[dev]' + >> pre-commit install + >> conda install pandoc + + +Notes: + +1) The single quotes around ``'[dev]'`` may not be required for your operating system. +2) ``pre-commit install`` will initialize pre-commit for this local repository, so + that a set of tests will be run prior to completing a local commit. For more + information, see the Python Project Template documentation on + `pre-commit `_. +3) Installing ``pandoc`` allows you to verify that automatic rendering of Jupyter notebooks + into documentation for ReadTheDocs works as expected. For more information, see + the Python Project Template documentation on + `Sphinx and Python Notebooks `_. + + +.. toctree:: + :hidden: + + Home page + API Reference + Notebooks diff --git a/docs/notebooks.rst b/docs/notebooks.rst new file mode 100644 index 0000000..7f7e544 --- /dev/null +++ b/docs/notebooks.rst @@ -0,0 +1,6 @@ +Notebooks +======================================================================================== + +.. toctree:: + + Introducing Jupyter Notebooks diff --git a/docs/notebooks/README.md b/docs/notebooks/README.md new file mode 100644 index 0000000..a521ae1 --- /dev/null +++ b/docs/notebooks/README.md @@ -0,0 +1 @@ +Put your Jupyter notebooks here :) diff --git a/docs/notebooks/intro_notebook.ipynb b/docs/notebooks/intro_notebook.ipynb new file mode 100644 index 0000000..3edb43d --- /dev/null +++ b/docs/notebooks/intro_notebook.ipynb @@ -0,0 +1,82 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "accepting-editor", + "metadata": { + "cell_marker": "\"\"\"" + }, + "source": [ + "# Introducing Jupyter Notebooks in Sphinx\n", + "\n", + "This notebook showcases very basic functionality of rendering your jupyter notebooks as tutorials inside your sphinx documentation.\n", + "\n", + "As part of the LINCC Frameworks python project template, your notebooks will be executed AND rendered at document build time.\n", + "\n", + "You can read more about Sphinx, ReadTheDocs, and building notebooks in [LINCC's documentation](https://lincc-ppt.readthedocs.io/en/latest/practices/sphinx.html)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "actual-thirty", + "metadata": {}, + "outputs": [], + "source": [ + "def sierpinsky(order):\n", + " \"\"\"Define a method that will create a Sierpinsky triangle of given order,\n", + " and will print it out.\"\"\"\n", + " triangles = [\"*\"]\n", + " for i in range(order):\n", + " spaces = \" \" * (2**i)\n", + " triangles = [spaces + triangle + spaces for triangle in triangles] + [\n", + " triangle + \" \" + triangle for triangle in triangles\n", + " ]\n", + " print(f\"Printing order {order} triangle\")\n", + " print(\"\\n\".join(triangles))" + ] + }, + { + "cell_type": "markdown", + "id": "coral-upper", + "metadata": { + "cell_marker": "\"\"\"", + "lines_to_next_cell": 1 + }, + "source": [ + "Then, call our method a few times. This will happen on the fly during notebook rendering." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "for order in range(3):\n", + " sierpinsky(order)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "sierpinsky(4)" + ] + } + ], + "metadata": { + "jupytext": { + "cell_markers": "\"\"\"" + }, + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..e4a22bb --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,7 @@ +sphinx +sphinx-rtd-theme +sphinx-autoapi +nbsphinx +ipython +jupytext +jupyter diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..d0841eb --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,65 @@ +[project] +name = "adler" +license = {file = "LICENSE"} +readme = "README.md" +authors = [ + { name = "Adler Team", email = "s.merritt@qub.ac.uk" } +] +classifiers = [ + "Development Status :: 4 - Beta", + "Intended Audience :: Developers", + "Intended Audience :: Science/Research", + "Operating System :: OS Independent", + "Programming Language :: Python", +] +dynamic = ["version"] +dependencies = [ + "ipykernel", # Support for Jupyter notebooks +] + +[project.urls] +"Source Code" = "https://github.com/lsst-uk/adler" + +# On a mac, install optional dependencies with `pip install '.[dev]'` (include the single quotes) +[project.optional-dependencies] +dev = [ + "pytest", + "pytest-cov", # Used to report total code coverage + "pre-commit", # Used to run checks before finalizing a git commit + "sphinx", # Used to automatically generate documentation + "sphinx-rtd-theme", # Used to render documentation + "sphinx-autoapi", # Used to automatically generate api documentation + "black", # Used for static linting of files + # if you add dependencies here while experimenting in a notebook and you + # want that notebook to render in your documentation, please add the + # dependencies to ./docs/requirements.txt as well. + "nbconvert", # Needed for pre-commit check to clear output from Python notebooks + "nbsphinx", # Used to integrate Python notebooks into Sphinx documentation + "ipython", # Also used in building notebooks into Sphinx +] + +[build-system] +requires = [ + "setuptools>=62", # Used to build and package the Python project + "setuptools_scm>=6.2", # Gets release version from git. Makes it available programmatically +] +build-backend = "setuptools.build_meta" + +[tool.setuptools_scm] +write_to = "src/adler/_version.py" + +[tool.pytest.ini_options] +testpaths = [ + "tests", +] + +[tool.black] +line-length = 110 +target-version = ["py38"] + +[tool.isort] +profile = "black" +line_length = 110 + +[tool.coverage.run] +omit=["src/adler/_version.py"] diff --git a/src/adler/__init__.py b/src/adler/__init__.py new file mode 100644 index 0000000..b564b85 --- /dev/null +++ b/src/adler/__init__.py @@ -0,0 +1,3 @@ +from .example_module import greetings, meaning + +__all__ = ["greetings", "meaning"] diff --git a/src/adler/example_module.py b/src/adler/example_module.py new file mode 100644 index 0000000..f76e837 --- /dev/null +++ b/src/adler/example_module.py @@ -0,0 +1,23 @@ +"""An example module containing simplistic functions.""" + + +def greetings() -> str: + """A friendly greeting for a future friend. + + Returns + ------- + str + A typical greeting from a software engineer. + """ + return "Hello from LINCC-Frameworks!" + + +def meaning() -> int: + """The meaning of life, the universe, and everything. + + Returns + ------- + int + The meaning of life. + """ + return 42 diff --git a/tests/adler/conftest.py b/tests/adler/conftest.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/adler/test_example_module.py b/tests/adler/test_example_module.py new file mode 100644 index 0000000..09bfb59 --- /dev/null +++ b/tests/adler/test_example_module.py @@ -0,0 +1,13 @@ +from adler import example_module + + +def test_greetings() -> None: + """Verify the output of the `greetings` function""" + output = example_module.greetings() + assert output == "Hello from LINCC-Frameworks!" + + +def test_meaning() -> None: + """Verify the output of the `meaning` function""" + output = example_module.meaning() + assert output == 42 From d8fe8b5d2970ed6d075ffc6a88dbdea217beb966 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci-lite[bot]" <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> Date: Tue, 30 Jan 2024 13:11:23 +0000 Subject: [PATCH 2/6] [pre-commit.ci lite] apply automatic fixes --- docs/notebooks/intro_notebook.ipynb | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/notebooks/intro_notebook.ipynb b/docs/notebooks/intro_notebook.ipynb index 3edb43d..e814ca4 100644 --- a/docs/notebooks/intro_notebook.ipynb +++ b/docs/notebooks/intro_notebook.ipynb @@ -50,6 +50,7 @@ { "cell_type": "code", "execution_count": null, + "id": "f93e79e9", "metadata": {}, "outputs": [], "source": [ @@ -60,6 +61,7 @@ { "cell_type": "code", "execution_count": null, + "id": "526ac5db", "metadata": {}, "outputs": [], "source": [ @@ -75,7 +77,7 @@ "display_name": "Python 3", "language": "python", "name": "python3" - } + } }, "nbformat": 4, "nbformat_minor": 5 From 2b9902a3faf411a4458ecb06acddc35ee65d50ab Mon Sep 17 00:00:00 2001 From: Meg Schwamb Date: Tue, 30 Jan 2024 13:19:49 +0000 Subject: [PATCH 3/6] Update intro_notebook.ipynb update notebook to a notebook that was run cells --- docs/notebooks/intro_notebook.ipynb | 73 ++++++++++++++++++++++++++--- 1 file changed, 67 insertions(+), 6 deletions(-) diff --git a/docs/notebooks/intro_notebook.ipynb b/docs/notebooks/intro_notebook.ipynb index e814ca4..48dbb2e 100644 --- a/docs/notebooks/intro_notebook.ipynb +++ b/docs/notebooks/intro_notebook.ipynb @@ -18,7 +18,7 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 1, "id": "actual-thirty", "metadata": {}, "outputs": [], @@ -49,10 +49,27 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 2, "id": "f93e79e9", "metadata": {}, - "outputs": [], + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Printing order 0 triangle\n", + "*\n", + "Printing order 1 triangle\n", + " * \n", + "* *\n", + "Printing order 2 triangle\n", + " * \n", + " * * \n", + " * * \n", + "* * * *\n" + ] + } + ], "source": [ "for order in range(3):\n", " sierpinsky(order)" @@ -60,13 +77,45 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 3, "id": "526ac5db", "metadata": {}, - "outputs": [], + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Printing order 4 triangle\n", + " * \n", + " * * \n", + " * * \n", + " * * * * \n", + " * * \n", + " * * * * \n", + " * * * * \n", + " * * * * * * * * \n", + " * * \n", + " * * * * \n", + " * * * * \n", + " * * * * * * * * \n", + " * * * * \n", + " * * * * * * * * \n", + " * * * * * * * * \n", + "* * * * * * * * * * * * * * * *\n" + ] + } + ], "source": [ "sierpinsky(4)" ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "ce7b9e93", + "metadata": {}, + "outputs": [], + "source": [] } ], "metadata": { @@ -74,9 +123,21 @@ "cell_markers": "\"\"\"" }, "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.5" } }, "nbformat": 4, From ee8be779956fadff46be95624219d39d35e80430 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci-lite[bot]" <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> Date: Tue, 30 Jan 2024 13:20:51 +0000 Subject: [PATCH 4/6] [pre-commit.ci lite] apply automatic fixes --- docs/notebooks/intro_notebook.ipynb | 51 +++-------------------------- 1 file changed, 5 insertions(+), 46 deletions(-) diff --git a/docs/notebooks/intro_notebook.ipynb b/docs/notebooks/intro_notebook.ipynb index 48dbb2e..ea91419 100644 --- a/docs/notebooks/intro_notebook.ipynb +++ b/docs/notebooks/intro_notebook.ipynb @@ -18,7 +18,7 @@ }, { "cell_type": "code", - "execution_count": 1, + "execution_count": null, "id": "actual-thirty", "metadata": {}, "outputs": [], @@ -49,27 +49,10 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": null, "id": "f93e79e9", "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Printing order 0 triangle\n", - "*\n", - "Printing order 1 triangle\n", - " * \n", - "* *\n", - "Printing order 2 triangle\n", - " * \n", - " * * \n", - " * * \n", - "* * * *\n" - ] - } - ], + "outputs": [], "source": [ "for order in range(3):\n", " sierpinsky(order)" @@ -77,34 +60,10 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": null, "id": "526ac5db", "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Printing order 4 triangle\n", - " * \n", - " * * \n", - " * * \n", - " * * * * \n", - " * * \n", - " * * * * \n", - " * * * * \n", - " * * * * * * * * \n", - " * * \n", - " * * * * \n", - " * * * * \n", - " * * * * * * * * \n", - " * * * * \n", - " * * * * * * * * \n", - " * * * * * * * * \n", - "* * * * * * * * * * * * * * * *\n" - ] - } - ], + "outputs": [], "source": [ "sierpinsky(4)" ] From d815288fa13985c92220e4ff5b55e62d600b818c Mon Sep 17 00:00:00 2001 From: Meg Schwamb Date: Tue, 30 Jan 2024 13:25:09 +0000 Subject: [PATCH 5/6] Update intro_notebook.ipynb remove empty cell --- docs/notebooks/intro_notebook.ipynb | 59 ++++++++++++++++++++++------- 1 file changed, 46 insertions(+), 13 deletions(-) diff --git a/docs/notebooks/intro_notebook.ipynb b/docs/notebooks/intro_notebook.ipynb index ea91419..651deda 100644 --- a/docs/notebooks/intro_notebook.ipynb +++ b/docs/notebooks/intro_notebook.ipynb @@ -18,7 +18,7 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 1, "id": "actual-thirty", "metadata": {}, "outputs": [], @@ -49,10 +49,27 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 2, "id": "f93e79e9", "metadata": {}, - "outputs": [], + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Printing order 0 triangle\n", + "*\n", + "Printing order 1 triangle\n", + " * \n", + "* *\n", + "Printing order 2 triangle\n", + " * \n", + " * * \n", + " * * \n", + "* * * *\n" + ] + } + ], "source": [ "for order in range(3):\n", " sierpinsky(order)" @@ -60,21 +77,37 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 3, "id": "526ac5db", "metadata": {}, - "outputs": [], + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Printing order 4 triangle\n", + " * \n", + " * * \n", + " * * \n", + " * * * * \n", + " * * \n", + " * * * * \n", + " * * * * \n", + " * * * * * * * * \n", + " * * \n", + " * * * * \n", + " * * * * \n", + " * * * * * * * * \n", + " * * * * \n", + " * * * * * * * * \n", + " * * * * * * * * \n", + "* * * * * * * * * * * * * * * *\n" + ] + } + ], "source": [ "sierpinsky(4)" ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "ce7b9e93", - "metadata": {}, - "outputs": [], - "source": [] } ], "metadata": { From 54d89b8416d10e30bfe278a0c045bd4e6925e725 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci-lite[bot]" <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> Date: Tue, 30 Jan 2024 13:26:11 +0000 Subject: [PATCH 6/6] [pre-commit.ci lite] apply automatic fixes --- docs/notebooks/intro_notebook.ipynb | 51 +++-------------------------- 1 file changed, 5 insertions(+), 46 deletions(-) diff --git a/docs/notebooks/intro_notebook.ipynb b/docs/notebooks/intro_notebook.ipynb index 651deda..7eb282d 100644 --- a/docs/notebooks/intro_notebook.ipynb +++ b/docs/notebooks/intro_notebook.ipynb @@ -18,7 +18,7 @@ }, { "cell_type": "code", - "execution_count": 1, + "execution_count": null, "id": "actual-thirty", "metadata": {}, "outputs": [], @@ -49,27 +49,10 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": null, "id": "f93e79e9", "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Printing order 0 triangle\n", - "*\n", - "Printing order 1 triangle\n", - " * \n", - "* *\n", - "Printing order 2 triangle\n", - " * \n", - " * * \n", - " * * \n", - "* * * *\n" - ] - } - ], + "outputs": [], "source": [ "for order in range(3):\n", " sierpinsky(order)" @@ -77,34 +60,10 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": null, "id": "526ac5db", "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Printing order 4 triangle\n", - " * \n", - " * * \n", - " * * \n", - " * * * * \n", - " * * \n", - " * * * * \n", - " * * * * \n", - " * * * * * * * * \n", - " * * \n", - " * * * * \n", - " * * * * \n", - " * * * * * * * * \n", - " * * * * \n", - " * * * * * * * * \n", - " * * * * * * * * \n", - "* * * * * * * * * * * * * * * *\n" - ] - } - ], + "outputs": [], "source": [ "sierpinsky(4)" ]