set up documenter

.github/workflows/docs.yml

@@ -0,0 +1,24 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+    tags: '*'
+  pull_request:
+
+jobs:
+  docbuild:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: 1.8
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

docs/.gitignore

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

docs/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Preferences = "21216c6a-2e73-6563-6e65-726566657250"

docs/make.jl

@@ -0,0 +1,23 @@
+using Documenter
+using Preferences
+
+makedocs(
+    sitename = "Preferences",
+    format = Documenter.HTML(),
+    modules = [Preferences],
+    pages = [
+        "index.md",
+        "api.md",
+    ],
+)
+
+# Documenter can also automatically deploy documentation to gh-pages.
+# See "Hosting Documentation" and deploydocs() in the Documenter manual
+# for more information.
+deploydocs(
+    repo = "github.com/JuliaPackaging/Preferences.jl",
+    devbranch = "master",
+    push_preview = true,
+    forcepush = true,
+)
+

docs/src/api.md

@@ -0,0 +1,22 @@
+# API
+
+```@meta
+CurrentModule = Preferences
+```
+
+## External
+```@docs
+load_preference
+@load_preference
+has_preference
+@has_preference
+set_preferences!
+@set_preferences!
+delete_preferences!
+@delete_preferences!
+```
+
+## Internal
+```@docs
+process_sentinel_values!
+```

docs/src/index.md

@@ -0,0 +1,3 @@
+# Preferences.jl
+
+Documentation for Preferences.jl

src/Preferences.jl

@@ -21,7 +21,7 @@ Load a particular preference from the `Preferences.toml` file, shallowly merging
 as it walks the hierarchy of load paths, loading preferences from all environments that
 list the given UUID as a direct dependency.
 
-Most users should use the `@load_preference` convenience macro which auto-determines the
+Most users should use the [`@load_preference`](@ref) convenience macro which auto-determines the
 calling `Module`.
 """
 function load_preference(uuid::UUID, key::String, default = nothing)
@@ -39,7 +39,7 @@ end
 """
     @load_preference(key)
 
-Convenience macro to call `load_preference()` for the current package.
+Convenience macro to call [`load_preference()`](@ref) for the current package.
 """
 macro load_preference(key, default = nothing)
     return quote
@@ -51,8 +51,6 @@ end
     has_preference(uuid_or_module, key)
 
 Return `true` if the particular preference is found, and `false` otherwise.
-
-See the `has_preference` docstring for more details.
 """
 function has_preference(uuid::UUID, key::String)
     value = load_preference(uuid, key, nothing)
@@ -65,7 +63,7 @@ end
 """
     @has_preference(key)
 
-Convenience macro to call `has_preference()` for the current package.
+Convenience macro to call [`has_preference()`](@ref) for the current package.
 """
 macro has_preference(key)
     return quote
@@ -77,7 +75,7 @@ end
     process_sentinel_values!(prefs::Dict)
 
 Recursively search for preference values that end in `nothing` or `missing` leaves,
-which we handle specially, see the `set_preferences!()` docstring for more detail.
+which we handle specially, see the [`set_preferences!()`](@ref) docstring for more detail.
 """
 function process_sentinel_values!(prefs::Dict)
     # Need to widen `prefs` so that when we try to assign to `__clear__` below,
@@ -289,7 +287,7 @@ end
 """
     @set_preferences!(prefs...)
 
-Convenience macro to call `set_preferences!()` for the current package.  Defaults to
+Convenience macro to call [`set_preferences!()`](@ref) for the current package.  Defaults to
 setting `force=true`, since a package should have full control over itself, but not
 so for setting the preferences in other packages, pending private dependencies.
 """
@@ -305,8 +303,7 @@ end
 Deletes a series of preferences for the given UUID/Module, identified by the
 keys passed in as `prefs`.
 
-
-See the docstring for `set_preferences!`for more details.
+See the docstring for [`set_preferences!`](@ref) for more details.
 """
 function delete_preferences!(u::UUID, pref_keys::String...; block_inheritance::Bool = false, kwargs...)
     if block_inheritance
@@ -322,7 +319,7 @@ end
 """
     @delete_preferences!(prefs...)
 
-Convenience macro to call `delete_preferences!()` for the current package.  Defaults to
+Convenience macro to call [`delete_preferences!()`](@ref) for the current package.  Defaults to
 setting `force=true`, since a package should have full control over itself, but not
 so for deleting the preferences in other packages, pending private dependencies.
 """