From c7c24fbaf2700f22c71b7bde0cfee65a2065ec0d Mon Sep 17 00:00:00 2001 From: erinhmclark Date: Thu, 13 Mar 2025 20:26:29 +0000 Subject: [PATCH] Update style_guide.md to clarify pre-commit setup, add Docker commands to Makefile and merge ruff actions. --- .github/workflows/ruff.yaml | 7 +--- Makefile | 22 ++++++++---- docs/source/development/style_guide.md | 49 ++++++++++++++++++++------ 3 files changed, 56 insertions(+), 22 deletions(-) diff --git a/.github/workflows/ruff.yaml b/.github/workflows/ruff.yaml index 50407e5..40a6642 100644 --- a/.github/workflows/ruff.yaml +++ b/.github/workflows/ruff.yaml @@ -14,9 +14,4 @@ jobs: - name: Run Ruff (Lint & Format Check) uses: astral-sh/ruff-action@v1 with: - args: "check . --output-format=concise" - - - name: Run Ruff Format Check - uses: astral-sh/ruff-action@v1 - with: - args: "format --check ." + args: "check . --output-format=concise && ruff format --check ." diff --git a/Makefile b/Makefile index c59f272..7877543 100644 --- a/Makefile +++ b/Makefile @@ -13,7 +13,9 @@ help: @echo " make ruff-clean - Auto-fix Ruff linting and formatting issues" @echo " make docs - Generate documentation (same as 'make html')" @echo " make clean-docs - Remove generated docs" - @echo " make docker-run - Run the Docker container" + @echo " make docker-build - Build the Auto Archiver Docker image" + @echo " make docker-compose - Run Auto Archiver with Docker Compose" + @echo " make docker-compose-rebuild - Rebuild and run Auto Archiver with Docker Compose" @echo " make show-docs - Build and open the documentation in a browser" @@ -56,12 +58,20 @@ show-docs: @echo "Opening documentation in browser..." @open "$(BUILDDIR)/html/index.html" +.PHONY: docker-build +docker-build: + @echo "Building local Auto Archiver Docker image..." + @docker compose build # Uses the same build context as docker-compose.yml -# Run Docker with default settings -.PHONY: docker-run -docker-run: - @echo "Running Auto Archiver Docker container..." - @docker run --rm -v $PWD/secrets:/app/secrets -v $PWD/local_archive:/app/local_archive bellingcat/auto-archiver +.PHONY: docker-compose +docker-compose: + @echo "Running Auto Archiver with Docker Compose..." + @docker compose up + +.PHONY: docker-compose-rebuild +docker-compose-rebuild: + @echo "Rebuilding and running Auto Archiver with Docker Compose..." + @docker compose up --build # Catch-all for Sphinx commands .PHONY: Makefile diff --git a/docs/source/development/style_guide.md b/docs/source/development/style_guide.md index a73a6fc..e7fbded 100644 --- a/docs/source/development/style_guide.md +++ b/docs/source/development/style_guide.md @@ -1,21 +1,42 @@ -### Style Guide +# Style Guide + +## Ruff The project uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting. -Our style configurations are set in the `pyproject.toml` file. +Our style configurations are set in the `pyproject.toml` file, and can be modified from there. -We have a pre-commit hook to run the formatter before you commit, but Ruff can also be [integrated with most editors](https://docs.astral.sh/ruff/editors/setup/) to run automatically. +### Formatting + +We have a pre-commit hook to run the formatter before you commit. +This requires you to set it up once locally, then it will run automatically when you commit changes. + +```shell +poetry run pre-commit install +``` + +Ruff can also be [integrated with most editors](https://docs.astral.sh/ruff/editors/setup/) to run automatically. + +### Linting We recommend you also run the linter before pushing code. -# Running the linter - -We have Makefile commands to run common tasks (Note if you're on Windows you might need to install `make` first, or you can use ruff directly): +We have Makefile commands to run common tasks (Note if you're on Windows you might need to install `make` first, or alternatively you can use ruff commands directly): This outputs a report of any issues found: ```shell make ruff-check ``` +To see a more detailed linting report, you can remove the following line from the `pyproject.toml` file: +```toml +[tool.ruff] + +# Remove this for a more detailed lint report +output-format = "concise" +``` + +**Lint Fix** + This command will attempt to fix any issues it can: ⚠️ Warning: This can cause breaking changes. ⚠️ @@ -31,9 +52,17 @@ This is included with [Git for Windows](https://gitforwindows.org/) or you can i choco install make ``` -**Running directly with ruff** +**Changing the configs** -Alternatively, you can run the commands directly with ruff. +Our rules are quite lenient for general usage, but if you want to explore more rigorous checks you can check out the [ruff documentation](https://docs.astral.sh/ruff/configuration/). +You can then run checks with additional rules to see more nuanced errors which you can review manually. +One example is to extend the selected rules for linting the `pyproject.toml` file: -Our rules are quite lenient for general usage, but if you want to explore more rigorous checks you can explore the [ruff documentation](https://docs.astral.sh/ruff/configuration/). -You can then run checks to see more nuanced errors which you can review manually. \ No newline at end of file +```toml +[tool.ruff.lint] +# Extend the rules to check for by adding them to this option: +# See documentation for more details: https://docs.astral.sh/ruff/rules/ +extend-select = ["B"] +``` + +Then re-run the `make ruff-check` command to see the new rules in action. \ No newline at end of file