diff --git a/.travis.yml b/.travis.yml index 6c561455f9..e2ac879704 100644 --- 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 new file mode 100644 index 0000000000..a86db0591f --- /dev/null +++ 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 new file mode 100644 index 0000000000..359718f8da --- /dev/null +++ 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 index 8be2dcb1a8..f118bd3f6d 100644 --- 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 index 37c65e4e09..859848a304 100644 --- 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 index d172e8a975..fb6d7ea873 100644 --- 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 index 7c93b7c88c..3f578e943d 100644 --- 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 index 17bb5788d2..16254fdc87 100644 --- 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 index a2c8a82b45..47587121e3 100644 --- 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,7 +31,6 @@ include("DocChecks.jl") include("Writers/Writers.jl") include("Deps.jl") include("Generator.jl") -include("Travis.jl") import .Utilities: Selectors @@ -42,7 +38,7 @@ 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 `/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 `/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 diff --git a/src/Travis.jl b/src/Travis.jl deleted file mode 100644 index 2c8fc78a8e..0000000000 --- a/src/Travis.jl +++ /dev/null @@ -1,96 +0,0 @@ -""" -Package functions for interacting with Travis. - -$(EXPORTS) -""" -module Travis - -using DocStringExtensions -import Pkg -import Base64: base64encode - -export genkeys - -import LibGit2.GITHUB_REGEX - - -""" -$(SIGNATURES) - -Generate ssh keys for package `package` to automatically deploy docs from Travis to GitHub -pages. `package` can be either the name of a package or a path. Providing a path allows keys -to be generated for non-packages or packages that are not found in the Julia `LOAD_PATH`. -Use the `remote` keyword to specify the user and repository values. - -This function requires the following command lines programs to be installed: - -- `which` -- `git` -- `travis` -- `ssh-keygen` - -# Examples - -```jlcon -julia> using Documenter - -julia> Travis.genkeys("MyPackageName") -[ ... output ... ] - -julia> Travis.genkeys("MyPackageName", remote="organization") -[ ... output ... ] - -julia> Travis.genkeys("/path/to/target/directory") -[ ... output ... ] -``` -""" -function genkeys(package; remote="origin") - # Error checking. Do the required programs exist? - success(`which which`) || error("'which' not found.") - success(`which git`) || error("'git' not found.") - success(`which ssh-keygen`) || error("'ssh-keygen' not found.") - - directory = "docs" - filename = ".documenter" - - path = isdir(package) ? package : Pkg.dir(package, directory) - isdir(path) || error("`$path` not found. Provide a package name or directory.") - - cd(path) do - # Check for old '$filename.enc' and terminate. - isfile("$filename.enc") && - error("$package already has an ssh key. Remove it and try again.") - - # Are we in a git repo? - success(`git status`) || error("'Travis.genkey' only works with git repositories.") - - # Find the GitHub repo org and name. - user, repo = - let r = readchomp(`git config --get remote.$remote.url`) - m = match(GITHUB_REGEX, r) - m === nothing && error("no remote repo named '$remote' found.") - m[2], m[3] - end - - # Generate the ssh key pair. - success(`ssh-keygen -N "" -f $filename`) || error("failed to generated ssh key pair.") - - # Prompt user to add public key to github then remove the public key. - let url = "https://github.com/$user/$repo/settings/keys" - @info("add the public key below to $url with read/write access:") - println("\n", read("$filename.pub", String)) - rm("$filename.pub") - end - - # Base64 encode the private key and prompt user to add it to travis. The key is - # *not* encoded for the sake of security, but instead to make it easier to - # copy/paste it over to travis without having to worry about whitespace. - let url = "https://travis-ci.org/$user/$repo/settings" - @info("add a secure environment variable named 'DOCUMENTER_KEY' to $url with value:") - println("\n", base64encode(read(".documenter", String)), "\n") - rm(filename) - end - end -end - -end # module diff --git a/test/generate.jl b/test/generate.jl deleted file mode 100644 index 5093bba3c1..0000000000 --- a/test/generate.jl +++ /dev/null @@ -1,30 +0,0 @@ -module GenerateTests - -using Test -import Random: randstring -using Documenter - -@testset "Generate" begin - mktempdir() do root - let path = joinpath(root, "docs") - Documenter.generate("DocumenterTestPackage", dir = path) - @test isdir(path) - @test isfile(joinpath(path, "mkdocs.yml")) - @test isfile(joinpath(path, ".gitignore")) - @test isfile(joinpath(path, "make.jl")) - @test isdir(joinpath(path, "src")) - @test isfile(joinpath(path, "src", "index.md")) - end - end - - # # TODO: these tests should be reviewed. Documenter.generate() does not really - # # support Pkg3 / Julia 0.7 at the moment. - # @test_throws ErrorException Documenter.generate("Documenter") - # if VERSION < v"0.7.0-" - # @test_throws ErrorException Documenter.generate(randstring()) - # else - # @test_throws MethodError Documenter.generate(randstring()) - # end -end - -end diff --git a/test/runtests.jl b/test/runtests.jl index a2eeb109cb..482c81b976 100644 --- 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") @@ -49,9 +46,6 @@ println("="^50) # A simple build outside of a Git repository include("nongit/tests.jl") - - # Tests for Documenter.generate(). - include("generate.jl") end # Additional tests