Merge pull request #266 from FluxML/a2/docs-fix

Move to Documenter 1.0 (and some miscellaneous fixes)

Author: theabhirath

.github/workflows/CI.yml

@@ -113,14 +113,6 @@ jobs:
             using Pkg
             Pkg.develop(PackageSpec(path=pwd()))
             Pkg.instantiate()'
-      - run: |
-          julia --color=yes --project=docs/ -e '
-            using Metalhead
-            # using Pkg; Pkg.activate("docs")
-            using Documenter
-            using Documenter: doctest
-            DocMeta.setdocmeta!(Metalhead, :DocTestSetup, :(using Metalhead); recursive=true)
-            doctest(Metalhead)'
       - run: julia --project=docs docs/make.jl
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/Project.toml

@@ -5,4 +5,8 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Flux = "587475ba-b771-5e3f-ad9e-33799f191a9c"
 Images = "916415d5-f1e6-5110-898d-aaa5f9f070e0"
 LazyArtifacts = "4af54fe1-eca0-43a8-85a7-787d91b784e3"
+Metalhead = "dbeba491-748d-5e0e-a39e-b530a07fa0cc"
 Optimisers = "3bd65402-5787-11e9-1adc-39752487f4e2"
+
+[compat]
+Documenter = "1"

docs/make.jl

@@ -1,15 +1,12 @@
-using Documenter, Metalhead, Artifacts, LazyArtifacts, Images, DataAugmentation, Flux
-
-DocMeta.setdocmeta!(Metalhead, :DocTestSetup, :(using Metalhead); recursive = true)
+using Documenter, Metalhead
 
 # copy readme into index.md
 open(joinpath(@__DIR__, "src", "index.md"), "w") do io
     write(io, read(joinpath(@__DIR__, "..", "README.md"), String))
 end
 
-makedocs(; modules = [Metalhead, Artifacts, LazyArtifacts, Images, DataAugmentation, Flux],
+makedocs(; modules = [Metalhead],
          sitename = "Metalhead.jl",
-         doctest = false,
          pages = ["Home" => "index.md",
              "Tutorials" => [
                  "tutorials/quickstart.md",
@@ -41,7 +38,8 @@ makedocs(; modules = [Metalhead, Artifacts, LazyArtifacts, Images, DataAugmentat
                 "Model Utilities" => "api/utilities.md",
              ],
          ],
-         format = Documenter.HTML(; canonical = "https://fluxml.ai/Metalhead.jl/stable/",
+         warnonly = [:example_block, :missing_docs, :cross_references],
+         format = Documenter.HTML(canonical = "https://fluxml.ai/Metalhead.jl/stable/",
                                   #   analytics = "UA-36890222-9",
                                   assets = ["assets/flux.css"],
                                   prettyurls = get(ENV, "CI", nothing) == "true"))

src/Metalhead.jl

@@ -13,12 +13,12 @@ using Random
 
 import Functors
 
-# Utilities
-include("utilities.jl")
+# Model utilities
 include("core.jl")
 
 # Custom Layers
 include("layers/Layers.jl")
+include("layers/utilities.jl") # layer utilities
 using .Layers
 
 # CNN models

src/convnets/builders/resnet.jl

@@ -27,7 +27,7 @@ Creates a generic ResNet-like model.
   - `block_repeats`: This is a `Vector` of integers that specifies the number of repeats of each
     block in each stage.
   - `connection`: This is a function that determines the residual connection in the model. For
-    `resnets`, either of [`Metalhead.addact`](@ref) or [`Metalhead.actadd`](@ref) is recommended.
+    `resnets`, either of [`Metalhead.Layers.addact`](@ref) or [`Metalhead.Layers.actadd`](@ref) is recommended.
   - `classifier_fn`: This is a function that takes in the number of feature maps and returns a
     classifier. This is usually built as a closure using a function like [`Metalhead.create_classifier`](@ref).
     For example, if the number of output classes is `nclasses`, then the function can be defined as

src/convnets/resnets/core.jl

@@ -371,7 +371,7 @@ Wide ResNet, ResNeXt and Res2Net. For an _even_ more generic model API, see [`Me
   - `inplanes`: The number of input channels in the first convolutional layer.
   - `reduction_factor`: The reduction factor used in the model.
   - `connection`: This is a function that determines the residual connection in the model. For
-    `resnets`, either of [`Metalhead.addact`](@ref) or [`Metalhead.actadd`](@ref) is recommended.
+    `resnets`, either of [`Metalhead.Layers.addact`](@ref) or [`Metalhead.Layers.actadd`](@ref) is recommended.
     These decide whether the residual connection is added before or after the activation function.
   - `norm_layer`: The normalisation layer to be used in the model.
   - `revnorm`: set to `true` to place the normalisation layers before the convolutions

src/layers/Layers.jl

@@ -12,7 +12,7 @@ using Random
 
 import Flux.testmode!
 
-include("../utilities.jl")
+include("utilities.jl")
 
 include("attention.jl")
 export MultiHeadSelfAttention

src/layers/conv.jl

@@ -24,7 +24,7 @@ Create a convolution + normalisation layer pair with activation.
   - `pad`: padding of the convolution kernel
   - `dilation`: dilation of the convolution kernel
   - `groups`: groups for the convolution kernel
-  - `weight`, `init`: initialization for the convolution kernel (see [`Flux.Conv`](@ref))
+  - `weight`, `init`: initialization for the convolution kernel (see `Flux.Conv`)
 """
 function conv_norm(kernel_size::Dims{2}, inplanes::Integer, outplanes::Integer,
                    activation = relu; norm_layer = BatchNorm, revnorm::Bool = false,

src/layers/mbconv.jl

@@ -26,7 +26,7 @@ See Fig. 3 in [reference](https://arxiv.org/abs/1704.04861v1).
   - `bias`: whether to use bias in the convolution layers.
   - `stride`: stride of the first convolution kernel
   - `pad`: padding of the first convolution kernel
-  - `weight`, `init`: initialization for the convolution kernel (see [`Flux.Conv`](@ref))
+  - `weight`, `init`: initialization for the convolution kernel (see `Flux.Conv`)
 """
 function dwsep_conv_norm(kernel_size::Dims{2}, inplanes::Integer, outplanes::Integer,
                          activation = relu; norm_layer = BatchNorm, stride::Integer = 1,

src/utilities.jl renamed to src/layers/utilities.jl

@@ -14,16 +14,16 @@ end
 
 Convenience function for applying an activation function to the output after
 summing up the input arrays. Useful as the `connection` argument for the block
-function in [`Metalhead.resnet`](@ref).
+function in `Metalhead.resnet`.
 """
 addact(activation = relu, xs...) = activation(sum(xs))
 
 """
     actadd(activation = relu, xs...)
 
-Convenience function for adding input arrays after applying an activation
-function to them. Useful as the `connection` argument for the block function in
-[`Metalhead.resnet`](@ref).
+Convenience function for summing up the input arrays after applying an 
+activation function to them. Useful as the `connection` argument for the block 
+function in `Metalhead.resnet`.
 """
 actadd(activation = relu, xs...) = sum(activation.(x) for x in xs)