diff --git a/.gitignore b/.gitignore index b6e4761..56ff04e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,10 +1,7 @@ # Byte-compiled / optimized / DLL files __pycache__/ -*.py[cod] -*$py.class +.DS_Store -# C extensions -*.so # Distribution / packaging .Python @@ -27,15 +24,6 @@ share/python-wheels/ *.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/ @@ -51,79 +39,10 @@ coverage.xml .hypothesis/ .pytest_cache/ -# 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 -target/ +docs/built_examples/ # Jupyter Notebook .ipynb_checkpoints - -# IPython -profile_default/ -ipython_config.py - -# pyenv -.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 - -# PEP 582; used by e.g. github.com/David-OConnor/pyflow -__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/ diff --git a/README.md b/README.md index 5c49c7b..cc1386a 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,10 @@ -# examplePy -An example python package to be used in our tutorials +# examplePy + +An example Python package to be used in our pyOpenSci tutorials. + +## Learn more about pyOpenSci + +[Learn more about us. ](https://www.pyopensci.org) + + + 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..139becf --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,66 @@ +# 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 = 'examplePy' +copyright = '2022, pyOpenSci' +author = 'pyOpenSci' + +# The full version, including alpha/beta/rc tags +release = '0.1' + + +# -- 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 = ['nbsphinx', + "myst_parser", + # This loads a front end gallery for nbsphinx based on sphinx gallery + 'sphinx_gallery.load_style', + "sphinx_copybutton", +] + +# Sphinx gallery +sphinx_gallery_conf = { + 'examples_dirs': 'examples', # path to your example scripts + 'gallery_dirs': 'built_examples', # path to where to save gallery generated output +} + +# 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 = 'furo' + + +# 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.md b/docs/index.md new file mode 100644 index 0000000..44efdd1 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,21 @@ +# Welcome to examplePy's documentation! + + +Here is some content + +```{toctree} +:hidden: +:caption: Example + +Home +gallery +``` + + + + diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /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/docs/tutorials/index.md b/docs/tutorials/index.md new file mode 100644 index 0000000..4ab7d08 --- /dev/null +++ b/docs/tutorials/index.md @@ -0,0 +1,12 @@ +# Examples Gallery + +A gallery of tutorials. + +```{nbgallery} +--- +name: nbshpinx-gallery +glob: +--- +./* + +``` \ No newline at end of file diff --git a/docs/tutorials/plot_sample-2.ipynb b/docs/tutorials/plot_sample-2.ipynb new file mode 100644 index 0000000..6d45bbf --- /dev/null +++ b/docs/tutorials/plot_sample-2.ipynb @@ -0,0 +1,110 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "%matplotlib inline" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "# nbsphinx Seaborn example\n", + "\n", + "This example demonstrates a Seaborn plot. Figures produced Matplotlib **and**\n", + "by any package that is based on Matplotlib (e.g., Seaborn), will be\n", + "captured by default. See `image_scrapers` for details.\n", + "\n", + "This is taken from the sphinx gallery documentation :)\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "import matplotlib.pyplot as plt\n", + "import numpy as np" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "plt.rcParams['image.cmap'] = 'coolwarm'\n", + "plt.rcParams['image.origin'] = 'lower'\n", + "\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "x, y = np.meshgrid(np.arange(-3, 3, 0.1), np.arange(-2, 2, 0.1))\n", + "z = (1 - x / 2 + x ** 5 + y ** 3) * np.exp(-x ** 2 - y ** 2)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "zmax = np.max(np.abs(z))\n", + "print(zmax)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "fig, ax = plt.subplots(figsize=[5, 3.5])\n", + "ax.imshow(z, vmin=-zmax, vmax=zmax)\n", + "plt.show()" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "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.9.13" + } + }, + "nbformat": 4, + "nbformat_minor": 0 +} diff --git a/docs/tutorials/plot_sample.ipynb b/docs/tutorials/plot_sample.ipynb new file mode 100644 index 0000000..ebb6677 --- /dev/null +++ b/docs/tutorials/plot_sample.ipynb @@ -0,0 +1,92 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "%matplotlib inline" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "# nbsphinx Seaborn example\n", + "\n", + "This example demonstrates a Seaborn plot. Figures produced Matplotlib **and**\n", + "by any package that is based on Matplotlib (e.g., Seaborn), will be\n", + "captured by default. See `image_scrapers` for details.\n", + "\n", + "This is taken from the sphinx gallery documentation :)\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Author: Michael Waskom & Lucy Liu\n", + "# License: BSD 3 clause\n", + "\n", + "from __future__ import division, absolute_import, print_function\n", + "\n", + "\n", + "import numpy as np\n", + "import seaborn as sns\n", + "import matplotlib.pyplot as plt\n", + "\n", + "# Enforce the use of default set style\n", + "\n", + "# Create a noisy periodic dataset\n", + "y_array = np.array([])\n", + "x_array = np.array([])\n", + "rs = np.random.RandomState(8)\n", + "for _ in range(15):\n", + " x = np.linspace(0, 30 / 2, 30)\n", + " y = np.sin(x) + rs.normal(0, 1.5) + rs.normal(0, .3, 30)\n", + " y_array = np.append(y_array, y)\n", + " x_array = np.append(x_array, x)\n", + "\n", + "# Plot the average over replicates with confidence interval\n", + "sns.lineplot(y=y_array, x=x_array)\n", + "# to avoid text output\n", + "plt.show()" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "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.10.6 (main, Aug 30 2022, 04:58:14) [Clang 13.1.6 (clang-1316.0.21.2.5)]" + }, + "vscode": { + "interpreter": { + "hash": "b0fa6594d8f4cbf19f97940f81e996739fb7646882a419484c72d19e05852a7e" + } + } + }, + "nbformat": 4, + "nbformat_minor": 0 +} diff --git a/examplePy/__init__.py b/examplePy/__init__.py new file mode 100644 index 0000000..19799c4 --- /dev/null +++ b/examplePy/__init__.py @@ -0,0 +1,8 @@ +''' +The __init__.py file is required to import the directory as a package, and +can start empty. + +It is used for.... +''' + + diff --git a/examplePy/module1.py b/examplePy/module1.py new file mode 100644 index 0000000..37c4efa --- /dev/null +++ b/examplePy/module1.py @@ -0,0 +1,22 @@ +""" +More on this module here +""" + + +def add_values(num1, num2): + """A function that adds two integer values. + + Parameters + ---------- + num1 : int + mmm + num2 : int + mmm + + Returns + ------- + value : int + num 1 and num 2 added together + + """ + return num1 + num2 \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..91093cb --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,42 @@ +[build-system] +requires = ["setuptools>=61.0.0", "setuptools_scm[toml]>=6.2"] +build-backend = "setuptools.build_meta" + +[tool.setuptools_scm] +version_scheme = "post-release" +local_scheme = "node-and-date" # what does this do? +write_to = "verde/_version_generated.py" + +# https://packaging.python.org/en/latest/tutorials/packaging-projects/#configuring-metadata +# How do we know how much metadata to include? +[project] +name = "examplePy" +authors = [ + {name = "Some Maintainer", email = "some-email@pyopensci.org"} +] +maintainers = [{name = "All the contributors"}] +license = {text = "BSD 3-Clause"} +description = "An example Python package used to support Python packaging tutorials" +keywords = ["pyOpenSci", "python packaging"] +readme = "README.md" +# List of classifiers here: https://pypi.org/classifiers/ + +classifiers = [ + "Development Status :: 3 - Alpha", + "Intended Audience :: Science/Research", + "License :: OSI Approved :: BSD License", + "Operating System :: OS Independent", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3 :: Only", # when would I want to use this? + "Topic :: Education :: Testing", +] +requires-python = ">=3.8" +# Add one or two deps just cause +dependencies = [ +] + +[project.urls] +Home = "https://www.pyopensci.org/python-package-tutorials?" +Repository = "https://github.com/pyopensci/examplePy" +Documentation = "url-here" +Bug Tracker = "https://github.com/pyopensci/examplePy/issues" \ No newline at end of file diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..2ddb72b --- /dev/null +++ b/requirements.txt @@ -0,0 +1,9 @@ + +# for sphinx gallery only +sphinx-gallery +pillow +seaborn + +# theme and syntax +myst_parser +furo \ No newline at end of file