From 3f32ff269f394225afb0536afd607ea9689b4b3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20G=C3=B6ttgens?= Date: Wed, 5 Jul 2023 00:22:34 +0200 Subject: [PATCH] Update documentation (#159) Co-authored-by: Yuto Horikawa --- README.md | 37 ++-------------- docs/src/index.md | 109 +++++++++++++++++++++++++++++++++++++++++++--- src/Aqua.jl | 17 -------- 3 files changed, 106 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 04d38a0d..e67841a6 100644 --- a/README.md +++ b/README.md @@ -17,42 +17,13 @@ Aqua.jl provides functions to run a few automatable checks for Julia packages: * Check that all external packages listed in `deps` have corresponding `compat` entry. * `Project.toml` formatting is compatible with Pkg.jl output. -* There are no "obvious" type piracies ([**new in 0.6**](#notes-on-aqua-06)) +* There are no "obvious" type piracies. -See more in the [documentation](https://juliatesting.github.io/Aqua.jl/dev). +See more in the [documentation](https://juliatesting.github.io/Aqua.jl/). -## Quick usage +## Setup -Call `Aqua.test_all(YourPackage)` from `test/runtests.jl`, e.g., - -```julia -using YourPackage -using Aqua -Aqua.test_all(YourPackage) -``` - -## Notes on Aqua 0.6 - -Aqua 0.6 includes the type piracy detection, thanks to [the PR](https://github.com/JuliaTesting/Aqua.jl/pull/88) by Jakob -Nybo Nissen (@jakobnissen) and [the original implementation](https://discourse.julialang.org/t/pirate-hunter/20402) by -Frames Catherine White (@oxinabox). - -If this part of Aqua 0.6 causes a trouble, then you can disable the piracy detection -with a flag as in `Aqua.test_all(YourPackage; piracy = false)`. - -## Specifying Aqua version - -To avoid breaking test when a new Aqua.jl version is released, it is -recommended to add version bound for Aqua.jl in `test/Project.toml`: - -```toml -[deps] -Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595" -Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" - -[compat] -Aqua = "0.6" -``` +Please consult the [stable documentation](https://juliatesting.github.io/Aqua.jl/) and the the [dev documentation](https://juliatesting.github.io/Aqua.jl/dev/) for the latest instructions. ## Badge diff --git a/docs/src/index.md b/docs/src/index.md index 390c6733..e74d6a56 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,12 +1,107 @@ -# Aqua.jl +# Aqua.jl: +## *A*uto *QU*ality *A*ssurance for Julia packages -```@autodocs -Modules = [Aqua] -Private = false +Aqua.jl provides functions to run a few automatable checks for Julia packages: + +* There are no method ambiguities. +* There are no undefined `export`s. +* There are no unbound type parameters. +* There are no stale dependencies listed in `Project.toml`. +* Check that test target of the root project `Project.toml` and test project + (`test/Project.toml`) are consistent. +* Check that all external packages listed in `deps` have corresponding + `compat` entry. +* `Project.toml` formatting is compatible with Pkg.jl output. +* There are no "obvious" type piracies. + +## Quick usage + +Call `Aqua.test_all(YourPackage)` from the REPL, e.g., + +```julia +using YourPackage +using Aqua +Aqua.test_all(YourPackage) +``` + +## How to add Aqua.jl... + +### ...as a test dependency? + +There are two ways to add Aqua.jl as a test dependency to your package. +To avoid breaking tests when a new Aqua.jl version is released, it is +recommended to add a version bound for Aqua.jl. + + 1. In `YourPackage/test/Project.toml`, add Aqua.jl to `[dep]` and `[compat]` sections, like + ```toml + [deps] + Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595" + Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" + + [compat] + Aqua = "0.6" + ``` + + 2. In `YourPackage/Project.toml`, add Aqua.jl to `[compat]` and `[extras]` section and the `test` target, like + ```toml + [compat] + Aqua = "0.6" + + [extras] + Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595" + Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" + + [targets] + test = ["Aqua", "Test"] + ``` + +If your package supports Julia pre-1.2, you need to use the second approach, +although you can use both approaches at the same time. + +!!! warning + In normal use, `Aqua.jl` should not be added to `[deps]` in `YourPackage/Project.toml`! + +### ...to your tests? +It is recommended to create a separate file `YourPackage/test/Aqua.jl` that gets included in `YourPackage/test/runtests.jl` +with either + +```julia +using Aqua +Aqua.test_all(YourPackage) +``` +or some fine-grained checks with options, e.g., + +```julia +using Aqua + +@testset "Aqua.jl" begin + Aqua.test_all( + YourPackage; + ambiguities=(exclude=[SomePackage.some_function], broken=true), + unbound_args=true, + undefined_exports=true, + project_extras=true, + stale_deps=(ignore=[:SomePackage],), + deps_compat=(ignore=[:SomeOtherPackage],), + project_toml_formatting=true, + piracy=false, + ) +end +``` +For more details on the options, see the respective functions [below](@ref test_functions). + +### Example uses +The following is a small selection of packages that use Aqua.jl: +- [GAP.jl](https://github.com/oscar-system/GAP.jl) +- [Hecke.jl](https://github.com/thofma/Hecke.jl) +- [Oscar.jl](https://github.com/oscar-system/Oscar.jl) + +## [Test functions](@id test_functions) +```@docs +Aqua.test_all ``` ```@autodocs -Modules = [Aqua, Aqua.Piracy] -Public = false -Filter = t -> startswith(String(nameof(t)), "test_") +Modules = [Aqua] +Filter = t -> startswith(String(nameof(t)), "test_") && t != Aqua.test_all ``` diff --git a/src/Aqua.jl b/src/Aqua.jl index cec5fd1d..2f203016 100644 --- a/src/Aqua.jl +++ b/src/Aqua.jl @@ -1,10 +1,5 @@ module Aqua -@doc let path = joinpath(dirname(@__DIR__), "README.md") - include_dependency(path) - read(path, String) -end Aqua - using Base: PkgId, UUID using Pkg: Pkg, TOML using Test @@ -42,18 +37,6 @@ Run following tests in isolated testset: * [`test_project_toml_formatting(testtarget)`](@ref test_project_toml_formatting) * [`test_piracy(testtarget)`](@ref test_piracy) -!!! compat "Aqua.jl 0.5" - - Since Aqua.jl 0.5: - - * `test_all` runs [`test_ambiguities`](@ref) with `Core`. This - means method ambiguities of constructors can now be detected. - In Aqua.jl 0.4, `test_ambiguities` was invoked with - `[testtarget, Base]`. - - * `test_all` runs [`test_stale_deps`](@ref). In Aqua.jl 0.4, this - check was opt-in. - The keyword argument `\$x` (e.g., `ambiguities`) can be used to control whether or not to run `test_\$x` (e.g., `test_ambiguities`). If `test_\$x` supports keyword arguments, a `NamedTuple` can also be