Move Travis.genkeys and Documenter.generate to DocumenterTools.jl (#789)

JuliaDocs · Aug 16, 2018 · 7878718 · 7878718
1 parent af58ad7
commit 7878718
Show file tree

Hide file tree

Showing 12 changed files with 148 additions and 241 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -13,4 +13,6 @@ notifications:
   email: false
 
 after_success:
-  - julia -e 'cd(Pkg.dir("Documenter", "test")); include("coverage.jl")'
+  - 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
@@ -23,9 +23,13 @@ Documenter
 makedocs
 hide
 deploydocs
-Documenter.generate
-Travis
-Travis.genkeys
 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,10 +41,14 @@ 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.
 
-Open a Julia REPL and import [`Documenter`](@ref).
+SSH keys can be generated with the `Travis.genkeys` from the `DocumenterTools` package.
+Install and load it as
 
+```
+pkg> add DocumenterTools
+```
 ```jlcon
-julia> using Documenter
+julia> using DocumenterTools
 ```
 
 Then call the [`Travis.genkeys`](@ref) function as follows:
@@ -119,7 +123,7 @@ Add the following at the end of the file:
 ```julia
 deploydocs(
     repo = "github.com/USER_NAME/PACKAGE_NAME.jl.git",
-    julia = "0.6"
+    julia = "1.0"
 )
 ```
 

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)
 
 """
@@ -34,15 +31,14 @@ include("DocChecks.jl")
 include("Writers/Writers.jl")
 include("Deps.jl")
 include("Generator.jl")
-include("Travis.jl")
 
 import .Utilities: Selectors
 
 
 # User Interface.
 # ---------------
 
-export Travis, Deps, makedocs, deploydocs, hide
+export Deps, makedocs, deploydocs, hide
 
 """
     makedocs(
@@ -591,92 +587,4 @@ function getenv(regex::Regex)
     error("could not find key/iv pair.")
 end
 
-"""
-$(SIGNATURES)
-
-Creates a documentation stub for a package called `pkgname`. The location of
-the documentation is assumed to be `<package directory>/docs`, but this can
-be overriden with the keyword argument `dir`.
-
-It creates the following files
-
-```
-docs/
-    .gitignore
-    src/index.md
-    make.jl
-    mkdocs.yml
-```
-
-# Arguments
-
-**`pkgname`** is the name of the package (without `.jl`). It is used to
-determine the location of the documentation if `dir` is not provided.
-
-# Keywords
-
-**`dir`** defines the directory where the documentation will be generated.
-It defaults to `<package directory>/docs`. The directory must not exist.
-
-# Examples
-
-```jlcon
-julia> using Documenter
-
-julia> Documenter.generate("MyPackageName")
-[ ... output ... ]
-```
-"""
-function generate(pkgname::AbstractString; dir=nothing)
-    # TODO:
-    #   - set up deployment to `gh-pages`
-    #   - fetch url and username automatically (e.g from git remote.origin.url)
-
-    # Check the validity of the package name
-    if length(pkgname) == 0
-        error("Package name can not be an empty string.")
-    end
-    # Determine the root directory where we wish to generate the docs and
-    # check that it is a valid directory.
-    docroot = if dir === nothing
-        pkgdir = Pkg.dir(pkgname)
-        if !isdir(pkgdir)
-            error("Unable to find package $(pkgname).jl at $(pkgdir).")
-        end
-        joinpath(pkgdir, "docs")
-    else
-        dir
-    end
-
-    if ispath(docroot)
-        error("Directory $(docroot) already exists.")
-    end
-
-    # deploy the stub
-    try
-        @info("Deploying documentation to $(docroot)")
-        mkdir(docroot)
-
-        # create the root doc files
-        Generator.savefile(docroot, ".gitignore") do io
-            write(io, Generator.gitignore())
-        end
-        Generator.savefile(docroot, "make.jl") do io
-            write(io, Generator.make(pkgname))
-        end
-        Generator.savefile(docroot, "mkdocs.yml") do io
-            write(io, Generator.mkdocs(pkgname))
-        end
-
-        # Create the default documentation source files
-        Generator.savefile(docroot, "src/index.md") do io
-            write(io, Generator.index(pkgname))
-        end
-    catch
-        rm(docroot, recursive=true)
-        rethrow()
-    end
-    nothing
-end
-
-end
+end # module