Update documentation (#159)

Co-authored-by: Yuto Horikawa <[email protected]>

Author: lgoettgens

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
 

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
 ```

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