Skip to content

Commit

Permalink
Add pre-commit Git hooks to manage code style & QA during development (…
Browse files Browse the repository at this point in the history 
…#79)

* Add pre-commit to dev env for code style & QA mgmt

Added the pre-commit library into the development environment YAML file and
added the associated dependencies into the requirements.txt file.

* Add pre-commit configuration file

Add a new .pre-commit-config.yaml file which lists several predefined Git
pre-commit hooks and also includes a hook for code formatting with black. This
setup aims at enhancing code quality by setting up code style checking before
every commit.

* Delete trailing whitespace

* Add end of file newlines

* Update documentation re: pre-commit usage

This update replaces the documentation and guidance for using the `black` code
formatting tool with new instructions for using Git pre-commit hooks. It
provides the process for installing and using `pre-commit` in a newly cloned
repo to ensure consistent styling and quality across code, documentation, and
repository management. This includes the use of 'black' for code formatting.
  • Loading branch information
@douglatornell
douglatornell authored Apr 24, 2024
1 parent fc4eb8a commit 73acf7f
Show file tree
Hide file tree
Showing 8 changed files with 27,430 additions and 27,405 deletions.
21 changes: 21 additions & 0 deletions .pre-commit-config.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Git pre-commit hooks config file
# Only takes effect if you have pre-commit installed in the env,
# and after you run `pre-commit install`
#
# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
repos:
# Out-of-the-box hooks from the pre-commit org
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.6.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-toml
- id: check-added-large-files
# Code formatting with black
- repo: https://github.com/psf/black
rev: 24.4.1
hooks:
- id: black
3 changes: 3 additions & 0 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,9 @@ salishsea.eos.ubc.ca Site
| | .. image:: https://img.shields.io/badge/version%20control-git-blue.svg?logo=github |
| | :target: https://github.com/SalishSeaCast/salishsea-site |
| | :alt: Git on GitHub |
| | .. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white |
| | :target: https://pre-commit.com |
| | :alt: pre-commit |
| | .. image:: https://img.shields.io/badge/code%20style-black-000000.svg |
| | :target: https://black.readthedocs.io/en/stable/ |
| | :alt: The uncompromising Python code formatter |
Expand Down
2 changes: 1 addition & 1 deletion docs/Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,4 +17,4 @@ help:
# 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)
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
49 changes: 22 additions & 27 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,9 @@ salishsea.eos.ubc.ca Site Web App
| | .. image:: https://img.shields.io/badge/version%20control-git-blue.svg?logo=github |
| | :target: https://github.com/SalishSeaCast/salishsea-site |
| | :alt: Git on GitHub |
| | .. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white |
| | :target: https://pre-commit.com |
| | :alt: pre-commit |
| | .. image:: https://img.shields.io/badge/code%20style-black-000000.svg |
| | :target: https://black.readthedocs.io/en/stable/ |
| | :alt: The uncompromising Python code formatter |
Expand Down Expand Up @@ -235,44 +238,36 @@ To deactivate the environment use:
Coding Style
------------

.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
:target: https://pre-commit.com
:alt: pre-commit
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://black.readthedocs.io/en/stable/
:alt: The uncompromising Python code formatter

The :kbd:`salishsea-site` package uses the `black`_ code formatting tool to maintain a coding style that is very close to `PEP 8`_.
The :kbd:`salishsea-site` package uses Git pre-commit hooks managed by `pre-commit`_
to maintain consistent code style and and other aspects of code,
docs,
and repo QA.

.. _black: https://black.readthedocs.io/en/stable/
.. _PEP 8: https://peps.python.org/pep-0008/
.. _pre-commit: https://pre-commit.com/

:command:`black` is installed as part of the :ref:`SalishSeaSiteDevelopmentEnvironment` setup.

o run :command:`black` on the entire code-base use:
To install the `pre-commit` hooks in a newly cloned repo,
activate the conda development environment,
and run :command:`pre-commit install`:

.. code-block:: bash
$ cd SalishSeaCmd
$ conda activate salishsea-cmd
(salishsea-cmd)$ black ./
$ cd salishsea-site
$ conda activate salishsea-site
(salishsea-site)$ pre-commit install
in the repository root directory.
The output looks something like::
reformatted /media/doug/warehouse/MEOPAR/salishsea-site/salishsea_site/mako_filters.py
reformatted /media/doug/warehouse/MEOPAR/salishsea-site/salishsea_site/views/site.py
reformatted /media/doug/warehouse/MEOPAR/salishsea-site/salishsea_site/views/about.py
reformatted /media/doug/warehouse/MEOPAR/salishsea-site/salishsea_site/views/bloomcast.py
reformatted /media/doug/warehouse/MEOPAR/salishsea-site/tests/conftest.py
reformatted /media/doug/warehouse/MEOPAR/salishsea-site/tests/test_mako_filters.py
reformatted /media/doug/warehouse/MEOPAR/salishsea-site/tests/views/test_bloomcast.py
reformatted /media/doug/warehouse/MEOPAR/salishsea-site/tests/views/test_figures.py
reformatted /media/doug/warehouse/MEOPAR/salishsea-site/salishsea_site/views/wwatch3.py
reformatted /media/doug/warehouse/MEOPAR/salishsea-site/salishsea_site/views/figures.py
reformatted /media/doug/warehouse/MEOPAR/salishsea-site/salishsea_site/__init__.py
reformatted /media/doug/warehouse/MEOPAR/salishsea-site/salishsea_site/views/fvcom.py
reformatted /media/doug/warehouse/MEOPAR/salishsea-site/tests/views/test_salishseacast.py
reformatted /media/doug/warehouse/MEOPAR/salishsea-site/salishsea_site/views/salishseacast.py
All done! ✨ 🍰 ✨
14 files reformatted, 4 file left unchanged.
.. note::
You only need to install the hooks once immediately after you make a new clone of the
`salishsea-site repository`_ and build your :ref:`SalishSeaSiteDevelopmentEnvironment`.

.. _salishsea-site repository: https://github.com/SalishSeaCast/salishsea-site


.. _SalishSeaSiteRunningDevApp:
Expand Down
3 changes: 2 additions & 1 deletion envs/environment-dev.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,10 @@ dependencies:
- pyyaml
- requests

# For coding style, and pkg management
# For coding style, repo QA, and pkg management
- black
- hatch
- pre-commit

# For unit tests
- pytest
Expand Down
5 changes: 5 additions & 0 deletions envs/requirements.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ black==24.4.0
Brotli==1.1.0
certifi==2024.2.2
cffi==1.16.0
cfgv==3.3.1
charset-normalizer==3.3.2
click==8.1.7
colorama==0.4.6
Expand All @@ -36,6 +37,7 @@ httpx==0.27.0
hupper==1.12.1
hyperframe==6.0.1
hyperlink==21.0.0
identify==2.5.36
idna==3.7
imagesize==1.4.1
importlib_metadata==7.1.0
Expand All @@ -53,6 +55,7 @@ MarkupSafe==2.1.5
mdurl==0.1.2
more-itertools==10.2.0
mypy-extensions==1.0.0
nodeenv==1.8.0
packaging==24.0
PasteDeploy==3.1.0
pathspec==0.12.1
Expand All @@ -62,6 +65,7 @@ plaster==1.1.2
plaster-pastedeploy==1.0.1
platformdirs==4.2.0
pluggy==1.5.0
pre_commit==3.7.0
ptyprocess==0.7.0
pycparser==2.22
Pygments==2.17.2
Expand Down Expand Up @@ -102,6 +106,7 @@ translationstring==1.4
trove-classifiers==2024.4.10
types-python-dateutil==2.9.0.20240316
typing_extensions==4.11.0
ukkonen==1.0.1
urllib3==2.2.1
userpath==1.7.0
venusian==3.1.0
Expand Down
2 changes: 1 addition & 1 deletion salishsea_site/static/css/bootswatch-3.3.7/superhero/bootstrap.min.css
View file

Large diffs are not rendered by default.

Loading

0 comments on commit 73acf7f

Please sign in to comment.