Migrate docs to Documenter.jl

.github/workflows/CI.yml

@@ -9,6 +9,12 @@ on:
       - master
     tags: '*'
 
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+
 jobs:
   test:
     name: ${{ matrix.suite }} - Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }}
@@ -93,3 +99,29 @@ jobs:
       - uses: codecov/codecov-action@v2
         with:
           file: lcov.info
+
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1.6'
+      - run: |
+          julia --project=docs -e '
+            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 }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

.github/workflows/clean_preview.yml

@@ -0,0 +1,27 @@
+# from https://github.com/CliMA/ClimaTimeSteppers.jl
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v2
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+            if [ -d "previews/PR$PRNUM" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "[email protected]"
+              git rm -rf "previews/PR$PRNUM"
+              git commit -m "delete preview"
+              git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+              git push --force origin gh-pages-new:gh-pages
+            fi
+        env:
+            PRNUM: ${{ github.event.number }}

.github/workflows/pr_comment.yml

@@ -0,0 +1,14 @@
+name: pr_comment
+on:
+  pull_request:
+    types: [labeled]
+jobs:
+  pr_comment:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create PR comment
+        if: github.event_name == 'pull_request' && github.repository == github.event.pull_request.head.repo.full_name && github.event.label.name == 'documentation' # if this is a pull request build AND the pull request is NOT made from a fork
+        uses: thollander/actions-comment-pull-request@71efef56b184328c7ef1f213577c3a90edaa4aff
+        with:
+          message: 'Once the documentation build has completed, you can preview any updated documentation at this URL: https://fluxml.ai/Metalhead.jl/previews/PR${{ github.event.number }}/'
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -9,36 +9,36 @@
 ## Installation
 
 ```julia
-]add Metalhead
+julia> ]add Metalhead
 ```
 
 ## Available models
 
-| Model Name                                       | Function                                                                                  | Pre-trained? |
-|:-------------------------------------------------|:------------------------------------------------------------------------------------------|:------------:|
-| [VGG](https://arxiv.org/abs/1409.1556)           | [`VGG`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.VGG.html)                 | Y (w/o BN)   |
-| [ResNet](https://arxiv.org/abs/1512.03385)       | [`ResNet`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.ResNet.html)           | Y            |
-| [WideResNet](https://arxiv.org/abs/1605.07146)   | [`WideResNet`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.WideResNet.html) | Y            |
-| [GoogLeNet](https://arxiv.org/abs/1409.4842)     | [`GoogLeNet`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.GoogLeNet.html)     | N            |
-| [Inception-v3](https://arxiv.org/abs/1512.00567) | [`Inceptionv3`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.Inceptionv3.html)   | N            |
-| [Inception-v4](https://arxiv.org/abs/1602.07261) | [`Inceptionv4`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.Inceptionv4.html)   | N            |
-| [InceptionResNet-v2](https://arxiv.org/abs/1602.07261) | [`Inceptionv3`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.InceptionResNetv2.html)   | N            |
-| [SqueezeNet](https://arxiv.org/abs/1602.07360)   | [`SqueezeNet`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.SqueezeNet.html)   | Y            |
-| [DenseNet](https://arxiv.org/abs/1608.06993)     | [`DenseNet`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.DenseNet.html)       | N            |
-| [ResNeXt](https://arxiv.org/abs/1611.05431)      | [`ResNeXt`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.ResNeXt.html)         | Y            |
-| [MobileNetv1](https://arxiv.org/abs/1704.04861)  | [`MobileNetv1`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.MobileNetv1.html) | N            |
-| [MobileNetv2](https://arxiv.org/abs/1801.04381)  | [`MobileNetv2`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.MobileNetv2.html) | N            |
-| [MobileNetv3](https://arxiv.org/abs/1905.02244)  | [`MobileNetv3`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.MobileNetv3.html) | N            |
-| [EfficientNet](https://arxiv.org/abs/1905.11946) | [`EfficientNet`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.EfficientNet.html) | N            |
-| [MLPMixer](https://arxiv.org/pdf/2105.01601)     | [`MLPMixer`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.MLPMixer.html)       | N            |
-| [ResMLP](https://arxiv.org/abs/2105.03404)       | [`ResMLP`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.ResMLP.html)           | N            |
-| [gMLP](https://arxiv.org/abs/2105.08050)         | [`gMLP`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.gMLP.html)               | N            |
-| [ViT](https://arxiv.org/abs/2010.11929)          | [`ViT`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.ViT.html)                 | N            |
-| [ConvNeXt](https://arxiv.org/abs/2201.03545)     | [`ConvNeXt`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.ConvNeXt.html)       | N            |
-| [ConvMixer](https://arxiv.org/abs/2201.09792)    | [`ConvMixer`](https://fluxml.ai/Metalhead.jl/dev/docstrings/Metalhead.ConvMixer.html)     | N            |
-
-To contribute new models, see our [contributing docs](https://fluxml.ai/Metalhead.jl/dev/docs/dev-guide/contributing.html).
+| Model Name                                       | Function                                                                                       | Pre-trained? |
+|:-------------------------------------------------|:-----------------------------------------------------------------------------------------------|:------------:|
+| [VGG](https://arxiv.org/abs/1409.1556)           | [`VGG`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.VGG)                   | Y (w/o BN)   |
+| [ResNet](https://arxiv.org/abs/1512.03385)       | [`ResNet`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.ResNet)             | Y            |
+| [WideResNet](https://arxiv.org/abs/1605.07146)   | [`WideResNet`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.WideResNet)     | Y            |
+| [GoogLeNet](https://arxiv.org/abs/1409.4842)     | [`GoogLeNet`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.GoogLeNet)       | N            |
+| [Inception-v3](https://arxiv.org/abs/1512.00567) | [`Inceptionv3`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.Inceptionv3)   | N            |
+| [Inception-v4](https://arxiv.org/abs/1602.07261) | [`Inceptionv4`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.Inceptionv4)   | N            |
+| [InceptionResNet-v2](https://arxiv.org/abs/1602.07261) | [`Inceptionv3`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.InceptionResNetv2) | N            |
+| [SqueezeNet](https://arxiv.org/abs/1602.07360)   | [`SqueezeNet`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.SqueezeNet)     | Y            |
+| [DenseNet](https://arxiv.org/abs/1608.06993)     | [`DenseNet`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.DenseNet)         | N            |
+| [ResNeXt](https://arxiv.org/abs/1611.05431)      | [`ResNeXt`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.ResNeXt)           | Y            |
+| [MobileNetv1](https://arxiv.org/abs/1704.04861)  | [`MobileNetv1`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.MobileNetv1)   | N            |
+| [MobileNetv2](https://arxiv.org/abs/1801.04381)  | [`MobileNetv2`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.MobileNetv2)   | N            |
+| [MobileNetv3](https://arxiv.org/abs/1905.02244)  | [`MobileNetv3`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.MobileNetv3)   | N            |
+| [EfficientNet](https://arxiv.org/abs/1905.11946) | [`EfficientNet`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.EfficientNet) | N            |
+| [MLPMixer](https://arxiv.org/pdf/2105.01601)     | [`MLPMixer`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.MLPMixer)         | N            |
+| [ResMLP](https://arxiv.org/abs/2105.03404)       | [`ResMLP`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.ResMLP)             | N            |
+| [gMLP](https://arxiv.org/abs/2105.08050)         | [`gMLP`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.gMLP)                 | N            |
+| [ViT](https://arxiv.org/abs/2010.11929)          | [`ViT`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.ViT)                   | N            |
+| [ConvNeXt](https://arxiv.org/abs/2201.03545)     | [`ConvNeXt`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.ConvNeXt)         | N            |
+| [ConvMixer](https://arxiv.org/abs/2201.09792)    | [`ConvMixer`](https://fluxml.ai/Metalhead.jl/stable/api/reference.html#Metalhead.ConvMixer)       | N            |
+
+To contribute new models, see our [contributing docs](https://fluxml.ai/Metalhead.jl/latest/contributing/).
 
 ## Getting Started
 
-You can find the Metalhead.jl getting started guide [here](https://fluxml.ai/Metalhead.jl/dev/docs/tutorials/quickstart.html).
+You can find the Metalhead.jl getting started guide [here](https://fluxml.ai/Metalhead.jl/latest/tutorials/quickstart/).

docs/.gitignore

@@ -0,0 +1,2 @@
+build/
+site/

docs/Project.toml

@@ -1,6 +1,8 @@
 [deps]
+Artifacts = "56f22d72-fd6d-98f1-02f0-08ddc0907c33"
 DataAugmentation = "88a5189c-e7ff-4f85-ac6b-e6158070f02e"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Flux = "587475ba-b771-5e3f-ad9e-33799f191a9c"
 Images = "916415d5-f1e6-5110-898d-aaa5f9f070e0"
-Metalhead = "dbeba491-748d-5e0e-a39e-b530a07fa0cc"
-Publish = "f065f642-d108-4f50-8aa5-6749150a895a"
+LazyArtifacts = "4af54fe1-eca0-43a8-85a7-787d91b784e3"
+OneHotArrays = "0b1bfda6-eb8a-41d2-88d8-f5af5cad476f"

docs/make.jl

@@ -1,17 +1,26 @@
-using Pkg
+using Documenter, Metalhead, Artifacts, LazyArtifacts, Images, OneHotArrays, DataAugmentation, Flux
 
-Pkg.develop(; path = "..")
+DocMeta.setdocmeta!(Metalhead, :DocTestSetup, :(using Metalhead); recursive = true)
 
-using Publish
-using Artifacts, LazyArtifacts
-using Metalhead
+makedocs(modules = [Metalhead, Artifacts, LazyArtifacts, Images, OneHotArrays, DataAugmentation, Flux],
+         sitename = "Metalhead.jl",
+         doctest = false,
+         pages = ["Home" => "index.md",
+                  "Tutorials" => [
+                      "tutorials/quickstart.md",
+                   ],
+                  "Developer guide" => "contributing.md",
+                  "API reference" => [
+                      "api/reference.md",
+                   ],
+                 ],
+         format = Documenter.HTML(
+              canonical = "https://fluxml.ai/Metalhead.jl/stable/",
+            #   analytics = "UA-36890222-9",
+              assets = ["assets/flux.css"],
+              prettyurls = get(ENV, "CI", nothing) == "true"),
+        )
 
-# override default theme
-cp(artifact"flux-theme", "../_flux-theme"; force = true)
-
-p = Publish.Project(Metalhead)
-
-function build_and_deploy(label)
-    rm(label; recursive = true, force = true)
-    return deploy(Metalhead; root = "/Metalhead.jl", label = label)
-end
+deploydocs(repo = "github.com/FluxML/Metalhead.jl.git",
+           target = "build",
+           push_preview = true)

docs/src/api/reference.md

@@ -0,0 +1,17 @@
+# API Reference
+
+The API reference of `Metalhead.jl`.
+
+**Note**: This page is still in progress.
+
+```@autodocs
+Modules = [Metalhead]
+```
+
+```@docs
+Metalhead.create_classifier
+Metalhead.squeeze_excite
+Metalhead.LayerScale
+Metalhead.DropBlock
+Metalhead.StochasticDepth
+```