From ec64f7213f6f0e33495b0cf0b29e0bc30da4e1a2 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Fri, 28 Jun 2024 10:57:49 -0600 Subject: [PATCH 1/2] Add: ruff setup and instructions on autoformatting with vscode --- .pre-commit-config.yaml | 6 +- .readthedocs.yaml | 4 - docs/documentation/code-format-lint.md | 98 +++++++++++++++++++ .../{ => documentation}/hatch-envs-scripts.md | 0 4 files changed, 102 insertions(+), 6 deletions(-) create mode 100644 docs/documentation/code-format-lint.md rename docs/{ => documentation}/hatch-envs-scripts.md (100%) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 6451cf5..f8796be 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -12,10 +12,12 @@ # To run on all files: pre-commit run --all-files ci: - # pyosMeta disables autofixing of PRs to simplify new contributor experience and cleaner git history + # We prefer to disable autofixing of PRs to simplify new contributor + # We use the autofix as an option before we merge to run linting if a conributor + # doesn't setup pre-commit (which can be confusing to new contributors) autofix_prs: false # Frequency of hook updates - autoupdate_schedule: weekly + autoupdate_schedule: quarterly repos: # Out of the box hooks for pre-commit https://github.com/pre-commit/pre-commit-hooks diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 3e435f2..c7e06e6 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -10,10 +10,6 @@ build: os: ubuntu-22.04 tools: python: "3.12" - # You can also specify other tool versions: - # nodejs: "19" - # rust: "1.64" - # golang: "1.19" # Build documentation in the "docs/" directory with Sphinx sphinx: diff --git a/docs/documentation/code-format-lint.md b/docs/documentation/code-format-lint.md new file mode 100644 index 0000000..6178b12 --- /dev/null +++ b/docs/documentation/code-format-lint.md @@ -0,0 +1,98 @@ +# Linting and Code Formatting + +In our [packaging guide](https://www.pyopensci.org/python-package-guide/package-structure-code/code-style-linting-format.html), we +discuss various linters and code formatters used in the scientific Python +ecosystem, including tools like: + +* [black](https://github.com/psf/black) +* [flake8](https://github.com/pycqa/flake8) +* [isort](https://pycqa.github.io/isort/) + +[Ruff](https://github.com/charliermarsh/ruff) is a tool that has been +quickly becoming more popular. It is written in the Rust programming language +and is fast. We like Ruff because it can perform both code formatting +(similar to Black) and linting (similar to Flake8). This makes your setup +simpler. + +## Running Linters with pre-commit + +There are a few ways to call the linters when you are working on your code. + +One option is to use pre-commit hooks. [pre-commit](https://pre-commit.com/) +runs any defined linters, code and text formatters, spellcheckers, and other +tools on your code locally when you use `git commit` to make a change. For +example: + +```bash +git commit -m "message here" +``` + +By configuring pre-commit hooks, you can automatically run tools like Ruff and +codespell on your code and documentation every time you commit. This ensures +consistency and catches errors early. + +While pre-commit is a powerful tool to add to your workflow, many do not like it: + +* For beginner contributors, running pre-commit hooks can be confusing. You need + to understand that each time you commit, it will run the checks. If it finds + issues in your files, it will not actually commit your files to history. This + can be confusing for even seasoned developers if they haven't used pre-commit + before. +* Some prefer to set up autoformatters that run every time you save a file in + your preferred code editor (like VSCode). More on that below. + +## Pre-commit.ci Bot + +The [pre-commit CI bot](https://pre-commit.ci/) integrates with your GitHub +repository to run pre-commit checks in an online continuous integration pipeline. +The bot will run any pre-commit hooks that you have set up on new pull requests +submitted to your repository. + +Pre-commit.ci can be a nice tool to use for pull requests if set up correctly. +Ideally, you can set pre-commit CI to run only when you call it in a pull +request. This way, if you have a new contributor (or a seasoned one) who doesn't +want to set up pre-commit locally, or someone who wants to submit a pull request +(e.g., as a first contribution!) fully from the GitHub interface, you can enable +the bot to run pre-commit checks and fixes in the pull request yourself, as a +maintainer, before you merge the PR. + +## Setting Up Autosave + +TODO: More here on setting this up in VSCode and other tools. + +# Setting Up Autosave for Ruff in VSCode and Spyder + +## VSCode + +1. Make sure you have the the Python extension for vscode installed: + +1. **Install Ruff:** + Ensure you have Ruff installed in your environment. You can install it using pip: + + ```bash + pip install ruff + ``` + +1. Configure VSCode to run Ruff on save: + +You can add this configuration to your workspace to ensure ruff is run on your +files every time you edit and save them. + +```json +{ + "[python]": { + "editor.formatOnSave": true, + "editor.defaultFormatter": "charliermarsh.ruff", + "editor.codeActionsOnSave": { + "source.fixAll": "always", + "source.organizeImports": "always", + }, + }, + // TODO: figure out how the formatter is selected for notebooks + "notebook.formatOnSave.enabled": true, +} +``` + +## Spyder + +todo: add instructions here diff --git a/docs/hatch-envs-scripts.md b/docs/documentation/hatch-envs-scripts.md similarity index 100% rename from docs/hatch-envs-scripts.md rename to docs/documentation/hatch-envs-scripts.md From 608d96f635cc66f272f51e106d16bf6cc24a3508 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 2 Jul 2024 14:28:52 -0600 Subject: [PATCH 2/2] Update docs/documentation/code-format-lint.md --- docs/documentation/code-format-lint.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/documentation/code-format-lint.md b/docs/documentation/code-format-lint.md index 6178b12..aec70cf 100644 --- a/docs/documentation/code-format-lint.md +++ b/docs/documentation/code-format-lint.md @@ -95,4 +95,4 @@ files every time you edit and save them. ## Spyder -todo: add instructions here +Autoformat with ruff is not yet a Spyder feature. See [this issue](https://github.com/spyder-ide/spyder/issues/21357) for discussions.