Major Refactor: Add Ruff Linting, Nox, and Pre-Commit Hook

.github/workflows/deploy.yml

@@ -83,7 +83,6 @@ jobs:
     name: Upload release to Test PyPI
     needs: [build]
     runs-on: ubuntu-latest
-    environment: pypi
     permissions:
       id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
     steps:

CODE_OF_CONDUCT.md

@@ -132,4 +132,3 @@ conduct enforcement ladder](https://github.com/mozilla/diversity).
 For answers to common questions about this code of conduct, see the
 FAQ at https://www.contributor-covenant.org/faq. Translations are
 available at https://www.contributor-covenant.org/translations.
-

CONTRIBUTING.md

@@ -126,14 +126,18 @@ At this point, we will be notified of the pull request and will read it over. We
 
 If your changes are integrated, you will be added as a Github contributor and as one of the authors of the package. Thank you for being part of `plenoptic`!
 
-### Code Quality and Linting
-We use [Ruff](https://docs.astral.sh/ruff/) for linting and formatting our Python code to maintain a consistent code style and catch potential errors early. To ensure your contributions meet these standards, please follow the guidelines below:
+### Code Style and Linting
+We use [Ruff](https://docs.astral.sh/ruff/) for linting and formatting our Python code to maintain a consistent code style and catch potential errors early. We run ruff as part of our CI and non-compliant code will not be merged!
 
 #### Using Ruff
 
-Ruff is a fast and comprehensive Python formatter and linter that checks for common style and code quality issues. It combines multiple tools, like Pyflakes, pycodestyle, isort, and other linting rules into one efficient tool, which are specified in `pyproject.toml`. Before submitting your code, make sure to run Ruff to catch any issues.
+Ruff is a fast and comprehensive Python formatter and linter that checks for common style and code quality issues. It combines multiple tools, like black, Pyflakes, pycodestyle, isort, and other linting rules into one efficient tool, which are specified in `pyproject.toml`. Before submitting your code, make sure to run Ruff to catch any issues. See other sections of this document for how to use `nox` and `pre-commit` to simplify this process.
 
-**Using Ruff for [Formatting](https://docs.astral.sh/ruff/formatter/#philosophy):**
+Ruff has two components, a [formatter](https://docs.astral.sh/ruff/formatter/) and a [linter](https://docs.astral.sh/ruff/linter/). Formatters and linters are both static analysis tools, but formatters "quickly check and reformat your code for stylistic consistency without changing the runtime behavior of the code", while linters "detect not just stylistic inconsistency but also potential logical bugs, and often suggest code fixes" (per [GitHub's readme project](https://github.com/readme/guides/formatters-linters-compilers)). There are many choices of formatters and linters in python; ruff aims to combine the features of many of them while being very fast.
+
+For both the formatter and the linter, you can run ruff without any additional arguments; our configuration option are stored in the `pyproject.toml` file and so don't need to be specified explicitly.
+
+##### Formatting:
 
 `ruff format` is the primary entrypoint to the formatter. It accepts a list of files or directories, and formats all discovered Python files:
 ```bash
@@ -143,7 +147,7 @@ ruff format path/to/file.py   # Format a single file.
 ```
 For the full list of supported options, run `ruff format --help`.
 
-**Using Ruff for [Linting](https://docs.astral.sh/ruff/linter/):**
+##### Using Ruff for Linting:
 
 To run Ruff on your code:
 ```bash
@@ -160,15 +164,29 @@ ruff --fix .
 Be careful with **unsafe fixes**, safe fixes are symbolized with the tools emoji and are listed [here](https://docs.astral.sh/ruff/rules/)!
 
 #### Ignoring Ruff Linting
-You may want to suppress lint errors, for example when too long lines (code `E501`) are desired because otherwise the url might not be readable anymore.
+In some cases, it may be acceptable to suppress lint errors, for example when too long lines (code `E501`) are desired because otherwise the url might not be readable anymore. These ignores will be evaluated on a case-by-case basis.
 You can do this by adding the following to the end of the line:
 
 ```bash
-# noqa: E501
+This line is tooooooo long. # noqa: E501
 ```
-If you want to suppress an error across an entire file, do this:
+If you want to suppress an error across an entire file, do this at the top of the file:
 ```bash
 # ruff: noqa: E501
+Below is my python script
+...
+...
+And any line living in this file can be as long as it wants  ...
+...
+```
+
+
+In some cases, you want to not only suppress the error message a linter throws but actually _disable_ a linting rule. An example might be if the import order matters and running `isort` would mess with this.
+Then you can introduce an [action comment](https://pycqa.github.io/isort/docs/configuration/action_comments.html) like this such that isort does _not_ sort the following packages alphabetically:
+
+```bash
+import numpy as np # isort: skip
+import my_package as mp # isort: skip
 ```
 
 For more details, refer to the [documentation](https://docs.astral.sh/ruff/linter/#error-suppression).
@@ -183,15 +201,22 @@ For more details, refer to the [documentation](https://docs.astral.sh/ruff/linte
   complete docstrings, but they probably should.
 
 #### Pre-Commit Hooks:  Identifying simple issues before submission to code review (and how to ignore those)
-Pre-commit hooks are useful for the developer to check if all the linting and formatting rules (see Ruff above) are honored _before_ committing. That is, when you commit, pre-commit hooks are run and auto-fixed where applicable (e.g., trailing whitespace). You then need to add _again_ if you want these changes to be included in your commit.
+[Pre-commit](https://pre-commit.com/) hooks are useful for the developer to check if all the linting and formatting rules (see Ruff above) are honored _before_ committing. That is, when you commit, pre-commit hooks are run and auto-fixed where possible (e.g., trailing whitespace). You then need to add _again_ if you want these changes to be included in your commit. If the problem is not automatically fixable, you will need to manually update your code before you are able to commit.
+
+Using pre-commit is optional. We use [pre-commit.ci](https://pre-commit.ci/) to run pre-commit as part of PRs (auto-fixing wherever possible), but it may simplify your life to integrate pre-commit into your workflow.
+
+In order to use pre-commit, you must install the `pre-commit` package into your development environment, and then install the hooks:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
 
-Should you want to ignore pre-commit hooks, you can add `--no-verify` to your commit message like this:
+After installation, should you want to ignore pre-commit hooks for some reason (e.g., because you have to run to a meeting but don't have time to fix all the linting errors but still want your changes to be commited), you can add `--no-verify` to your commit message like this:
 ```bash
 git commit -m <my commit message> --no-verify
 ```
 
-All of the above only applies, if you have the pre-commit package manager installed using
-`pip install pre-commit`.
 
 ### Adding models or synthesis methods
 
@@ -272,6 +297,25 @@ nox
 
 `nox` will read the configuration from the `noxfile.py` script.
 
+If you only want to run an individual session (e.g., lint or test), you can first check which sessions are available with the following command:
+
+```bash
+nox -l
+```
+or
+```bash
+nox -list
+```
+
+Then you can use
+
+```bash
+nox -s <your_nox_session>
+```
+to run the session of your choice.
+
+Here are some examples:
+
 If you want to run just the tests, add the following option,
 
 ```bash
@@ -293,12 +337,14 @@ nox -s coverage
 `nox` offers a variety of configuration options, you can learn more about it from their
 [documentation](https://nox.thea.codes/en/stable/config.html).
 
+Note that nox works particularly well with pyenv, discussed later in this file, which makes it easy to install the multiple python versions used in testing.
+
 #### Multi-python version testing with pyenv
 Sometimes, before opening a pull-request that will trigger the `.github/workflow/ci.yml` continuous
 integration workflow, you may want to test your changes over all the supported python versions locally.
 
 Handling multiple installed python versions on the same machine can be challenging and confusing.
-[`pyenv`](https://github.com/pyenv/pyenv) is a great tool that really comes to the rescue.
+[`pyenv`](https://github.com/pyenv/pyenv) is a great tool that really comes to the rescue. Note that `pyenv` just handles python versions --- virtual environments have to be handled separately, using [`pyenv-virtualenv`](https://github.com/pyenv/pyenv-virtualenv)!
 
 This tool doesn't come with the package dependencies and has to be installed separately. Installation instructions
 are system specific but the package readme is very details, see
@@ -346,9 +392,7 @@ If you want to run `nox` on multiple python versions, all you need to do is:
 
 Note that `noxfile.py` lists the available option as keyword arguments in a session specific manner.
 
-If you have multiple python version installed, we recommend to manage your virtual environments
-through `pyenv`. For that you'll need to install the extension
-[`pyenv-virtualenv`](https://github.com/pyenv/pyenv-virtualenv).
+As mentioned earlier, if you have multiple python version installed, we recommend you manage your virtual environments through `pyenv` using the [`pyenv-virtualenv`](https://github.com/pyenv/pyenv-virtualenv) extension.
 
 This tool works with most of the environment managers including (`venv` and `conda`).
 Creating an environment with it is as simple as calling,

docs/conceptual_intro.rst

@@ -69,14 +69,14 @@ only use three numbers, often called RGB (red, green, and blue) --- why can we
 get away with throwing away so much information? Trichromacy and color metamers
 can help explain.
 
-Researchers studying color perception arrived at a standard procedure -- the bipartite color-matching experiment -- for 
+Researchers studying color perception arrived at a standard procedure -- the bipartite color-matching experiment -- for
 constraining a model for trichromatic metamers, illustrated in :numref:`trichromacy`. An observer matches a monochromatic test
 color (i.e., a light with energy at only a single wavelength) with the physical
 mixture of three different monochromatic stimuli, called **primaries**. Thus,
-the goal is to create two perceptually-indistinguishable stimuli (**metamers**). 
+the goal is to create two perceptually-indistinguishable stimuli (**metamers**).
 Perhaps surprisingly, not only is this possible for any test
 color, it is also possible for just about any selection of primaries (as long as they're within the
-visible light spectrum and sufficiently different from each other). For most human observers, three 
+visible light spectrum and sufficiently different from each other). For most human observers, three
 primaries are required: there are many colors that cannot be matched with only two primaries, and four yields non-unique responses.
 However, there are some people, for whom two primaries are sufficient.
 
@@ -87,9 +87,9 @@ However, there are some people, for whom two primaries are sufficient.
 
    Color matching experiment
 
-Requiring three primaries for most people, but two for some provided a hint regarding the underlying mechanisms: 
+Requiring three primaries for most people, but two for some provided a hint regarding the underlying mechanisms:
 most people have cone photorecpetors from three distinct classes (generally
-referred to as S, M, and L, for "short", "medium", and "long").  But some forms of color blindness arise from genetic 
+referred to as S, M, and L, for "short", "medium", and "long").  But some forms of color blindness arise from genetic
 deviations in which only two classes are represented. Color metamers are created when cone
 responses have been matched. Human cones transform colors from a
 high-dimensional space (i.e., a vector describing the energy at each wavelength)

docs/conf.py

@@ -12,20 +12,24 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('..'))
-sys.path.insert(0, os.path.abspath('./tutorials/'))
+
+import plenoptic
+
+sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, os.path.abspath("./tutorials/"))
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'plenoptic'
-copyright = '2019, Plenoptic authors'
-author = 'Plenoptic authors'
+project = "plenoptic"
+copyright = "2019, Plenoptic authors"
+author = "Plenoptic authors"
 
 # The short X.Y version
-version = ''
+version = ""
 # The full version, including alpha/beta/rc tags
-import plenoptic
+
+
 release = plenoptic.__version__
 
 # -- General configuration ---------------------------------------------------
@@ -34,51 +38,51 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.doctest',
-    'sphinx.ext.coverage',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.githubpages',
-    'sphinx.ext.napoleon',
-    'numpydoc',
-    'nbsphinx',
-    'nbsphinx_link',
-    'sphinxcontrib.apidoc',
-    'matplotlib.sphinxext.plot_directive',
-    'matplotlib.sphinxext.mathmpl',
-    'sphinx.ext.autodoc',
-    'sphinx_autodoc_typehints',
-    'sphinx.ext.intersphinx',
-    'sphinx_copybutton',
-    'sphinxemoji.sphinxemoji',
-    'sphinx_inline_tabs'
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.coverage",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.napoleon",
+    "numpydoc",
+    "nbsphinx",
+    "nbsphinx_link",
+    "sphinxcontrib.apidoc",
+    "matplotlib.sphinxext.plot_directive",
+    "matplotlib.sphinxext.mathmpl",
+    "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+    "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
+    "sphinxemoji.sphinxemoji",
+    "sphinx_inline_tabs",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+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']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # 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', '**.ipynb_checkpoints']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 # Napoleon settings
 napoleon_google_docstring = False
@@ -101,23 +105,22 @@
 # 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_rtd_theme"
 
 # 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']
+html_static_path = ["_static"]
 
 # these are for the sphinx_rtd_theme
 html_theme_options = {
-    'display_version': True,
-
+    "display_version": True,
 }
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'plenopticdoc'
+htmlhelp_basename = "plenopticdoc"
 
 
 # -- Options for LaTeX output ------------------------------------------------
@@ -126,15 +129,12 @@
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
-
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
-
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
@@ -144,19 +144,21 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'plenoptic.tex', 'plenoptic Documentation',
-     'Plenoptic authors', 'manual'),
+    (
+        master_doc,
+        "plenoptic.tex",
+        "plenoptic Documentation",
+        "Plenoptic authors",
+        "manual",
+    ),
 ]
 
 
 # -- Options for manual page output ------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'plenoptic', 'plenoptic Documentation',
-     [author], 1)
-]
+man_pages = [(master_doc, "plenoptic", "plenoptic Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output ----------------------------------------------
@@ -165,9 +167,15 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'plenoptic', 'plenoptic Documentation',
-     author, 'plenoptic', 'Visual Information Processing',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "plenoptic",
+        "plenoptic Documentation",
+        author,
+        "plenoptic",
+        "Visual Information Processing",
+        "Miscellaneous",
+    ),
 ]
 
 
@@ -186,7 +194,7 @@
 # epub_uid = ''
 
 # A list of files that should not be packed into the epub file.
-epub_exclude_files = ['search.html']
+epub_exclude_files = ["search.html"]
 
 
 # -- Extension configuration -------------------------------------------------