Include DocumenterTools test in Documenter docs.

JuliaDocs · Aug 15, 2018 · 39c3e83 · 39c3e83
1 parent 8b82a37
commit 39c3e83
Show file tree

Hide file tree

Showing 10 changed files with 140 additions and 28 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -13,4 +13,6 @@ notifications:
   email: false
 
 after_success:
+  - julia --project=docs -e 'using Pkg; Pkg.instantiate()'
+  - julia --project=docs docs/make.jl
   - julia -e 'cd("test"); include("coverage.jl")'
diff --git a/docs/Manifest.toml b/docs/Manifest.toml
@@ -0,0 +1,106 @@
+[[Base64]]
+uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
+
+[[Compat]]
+deps = ["Base64", "Dates", "DelimitedFiles", "Distributed", "InteractiveUtils", "LibGit2", "Libdl", "LinearAlgebra", "Markdown", "Mmap", "Pkg", "Printf", "REPL", "Random", "Serialization", "SharedArrays", "Sockets", "SparseArrays", "Statistics", "Test", "UUIDs", "Unicode"]
+git-tree-sha1 = "277d3807440d9793421354b6680911fc95d91a84"
+uuid = "34da2185-b29b-5c13-b0c7-acf172513d20"
+version = "1.0.1"
+
+[[Dates]]
+deps = ["Printf"]
+uuid = "ade2ca70-3891-5945-98fb-dc099432e06a"
+
+[[DelimitedFiles]]
+deps = ["Mmap"]
+uuid = "8bb1440f-4735-579b-a4ab-409b98df4dab"
+
+[[Distributed]]
+deps = ["LinearAlgebra", "Random", "Serialization", "Sockets"]
+uuid = "8ba89e20-285c-5b6f-9357-94700520ee1b"
+
+[[DocStringExtensions]]
+deps = ["Compat"]
+git-tree-sha1 = "a2ab006ff561a57eb858cee5314445b16c2fd2dd"
+uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
+version = "0.4.6"
+
+[[DocumenterTools]]
+deps = ["DocStringExtensions", "LibGit2"]
+git-tree-sha1 = "b28c164f4c5389cf5c111de4c2bec5541e6d5323"
+repo-rev = "master"
+repo-url = "https://github.com/JuliaDocs/DocumenterTools.jl"
+uuid = "46bb7b6e-9a58-11e8-21f8-9f2f45a0fcba"
+version = "0.0.0"
+
+[[InteractiveUtils]]
+deps = ["LinearAlgebra", "Markdown"]
+uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
+
+[[LibGit2]]
+uuid = "76f85450-5226-5b5a-8eaa-529ad045b433"
+
+[[Libdl]]
+uuid = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
+
+[[LinearAlgebra]]
+deps = ["Libdl"]
+uuid = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+
+[[Logging]]
+uuid = "56ddb016-857b-54e1-b83d-db4d58db5568"
+
+[[Markdown]]
+deps = ["Base64"]
+uuid = "d6f4376e-aef5-505a-96c1-9c027394607a"
+
+[[Mmap]]
+uuid = "a63ad114-7e13-5084-954f-fe012c677804"
+
+[[Pkg]]
+deps = ["Dates", "LibGit2", "Markdown", "Printf", "REPL", "Random", "SHA", "UUIDs"]
+uuid = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
+
+[[Printf]]
+deps = ["Unicode"]
+uuid = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+
+[[REPL]]
+deps = ["InteractiveUtils", "Markdown", "Sockets"]
+uuid = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
+
+[[Random]]
+deps = ["Serialization"]
+uuid = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+
+[[SHA]]
+uuid = "ea8e919c-243c-51af-8825-aaa63cd721ce"
+
+[[Serialization]]
+uuid = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
+
+[[SharedArrays]]
+deps = ["Distributed", "Mmap", "Random", "Serialization"]
+uuid = "1a1011a3-84de-559e-8e89-a11a2f7dc383"
+
+[[Sockets]]
+uuid = "6462fe0b-24de-5631-8697-dd941f90decc"
+
+[[SparseArrays]]
+deps = ["LinearAlgebra", "Random"]
+uuid = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+
+[[Statistics]]
+deps = ["LinearAlgebra", "SparseArrays"]
+uuid = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+
+[[Test]]
+deps = ["Distributed", "InteractiveUtils", "Logging", "Random"]
+uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[[UUIDs]]
+deps = ["Random"]
+uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
+
+[[Unicode]]
+uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -0,0 +1,2 @@
+[deps]
+DocumenterTools = "46bb7b6e-9a58-11e8-21f8-9f2f45a0fcba"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,7 +1,7 @@
-using Documenter
+using Documenter, DocumenterTools
 
 makedocs(
-    modules = [Documenter],
+    modules = [Documenter, DocumenterTools],
     clean = false,
     format = :html,
     assets = ["assets/favicon.ico"],
@@ -51,7 +51,7 @@ makedocs(
 deploydocs(
     repo = "github.com/JuliaDocs/Documenter.jl.git",
     target = "build",
-    julia = "nightly",
+    julia = "1.0",
     deps = nothing,
     make = nothing,
 )
diff --git a/docs/src/lib/public.md b/docs/src/lib/public.md
@@ -26,3 +26,10 @@ deploydocs
 Deps
 Deps.pip
 ```
+
+## DocumenterTools
+
+```@docs
+DocumenterTools.generate
+DocumenterTools.Travis.genkeys
+```
diff --git a/docs/src/man/guide.md b/docs/src/man/guide.md
@@ -2,13 +2,12 @@
 
 ## Installation
 
-Documenter is a registered package and so can be installed via `Pkg.add`.
+Documenter can be installed using the Julia package manager.
+From the Julia REPL, type `]` to enter the Pkg REPL mode and run
 
-```julia
-Pkg.add("Documenter")
 ```
-
-This package supports Julia `0.6` and `0.7-dev`.
+pkg> add Documenter
+```
 
 ## Usage
 
@@ -18,6 +17,10 @@ to creating a simple document.
 
 ### Setting up the folder structure
 
+!!! note
+    The function [`DocumenterTools.generate`](@ref) from the `DocumenterTools` package
+    can generate the basic structure that Documenters expects.
+
 Firstly, we need a Julia module to document. This could be a package generated via
 `PkgDev.generate` or a single `.jl` script accessible via Julia's `LOAD_PATH`. For this
 guide we'll be using a package called `Example.jl` that has the following directory layout:

diff --git a/docs/src/man/hosting.md b/docs/src/man/hosting.md
@@ -41,16 +41,12 @@ Deploy keys provide push access to a *single* repository, to allow secure deploy
     They are `which`, `git`, and `ssh-keygen`. Make sure these are installed before you
     begin this section.
 
-SSH keys can be generated with the `Travis.genkeys` from the `DocumenterTools.jl` package.
-DocumenterTools can be added using the Julia package manager. From the REPL, type `]`
-to enter the Pkg REPL mode and run
+SSH keys can be generated with the `Travis.genkeys` from the `DocumenterTools` package.
+Install and load it as
 
 ```
 pkg> add DocumenterTools
 ```
-
-DocumenterTools can now be loaded as
-
 ```jlcon
 julia> using DocumenterTools
 ```

diff --git a/src/DocChecks.jl b/src/DocChecks.jl
@@ -5,6 +5,7 @@ for checking docs.
 module DocChecks
 
 import ..Documenter:
+    Documenter,
     Documents,
     Utilities
 
@@ -83,7 +84,11 @@ sigs(::Any) = Type[Union{}]
 
 # Footnote checks.
 # ----------------
+"""
+$(SIGNATURES)
 
+Checks footnote links in a [`Documents.Document`](@ref).
+"""
 function footnotes(doc::Documents.Document)
     println(" > checking footnote links.")
     # A mapping of footnote ids to a tuple counter of how many footnote references and
@@ -143,6 +148,11 @@ footnote(other, orphans::Dict) = true
 
 hascurl() = (try; success(`curl --version`); catch err; false; end)
 
+"""
+$(SIGNATURES)
+
+Checks external links using curl.
+"""
 function linkcheck(doc::Documents.Document)
     if doc.user.linkcheck
         if hascurl()

diff --git a/src/Documenter.jl b/src/Documenter.jl
@@ -6,9 +6,6 @@ Two functions are exported from this module for public use:
 - [`makedocs`](@ref). Generates documentation from docstrings and templated markdown files.
 - [`deploydocs`](@ref). Deploys generated documentation from *Travis-CI* to *GitHub Pages*.
 
-Additionally it provides the unexported [`Documenter.generate`](@ref), which can be used to
-generate documentation stubs for new packages.
-
 $(EXPORTS)
 
 """
@@ -18,14 +15,6 @@ using DocStringExtensions
 import Base64: base64decode
 import Pkg
 
-# Deprecations
-# ------------
-Base.@deprecate_moved generate "DocumenterTools" false
-module Travis
-    Base.@deprecate_moved genkeys "DocumenterTools" false
-end
-export Travis
-
 # Submodules
 # ----------
 

diff --git a/test/runtests.jl b/test/runtests.jl
@@ -1,8 +1,5 @@
 using Test
 
-# Build the real docs first.
-include("../docs/make.jl")
-
 # Build the example docs
 include("examples/make.jl")