From 8b82a3760b03790643a24273f56f7676a35d743b Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Wed, 15 Aug 2018 14:13:38 +0200 Subject: [PATCH] Remove Documenter.generate() and Travis.genkeys() --- .travis.yml | 2 +- docs/src/lib/public.md | 3 -- docs/src/man/hosting.md | 14 ++++-- src/Documenter.jl | 101 ++++------------------------------------ src/Travis.jl | 96 -------------------------------------- test/generate.jl | 30 ------------ test/runtests.jl | 3 -- 7 files changed, 22 insertions(+), 227 deletions(-) delete mode 100644 src/Travis.jl delete mode 100644 test/generate.jl diff --git a/.travis.yml b/.travis.yml index 6c561455f9..ceadc94508 100644 --- a/.travis.yml +++ b/.travis.yml @@ -13,4 +13,4 @@ notifications: email: false after_success: - - julia -e 'cd(Pkg.dir("Documenter", "test")); include("coverage.jl")' + - julia -e 'cd("test"); include("coverage.jl")' diff --git a/docs/src/lib/public.md b/docs/src/lib/public.md index 37c65e4e09..5a9c685951 100644 --- a/docs/src/lib/public.md +++ b/docs/src/lib/public.md @@ -23,9 +23,6 @@ Documenter makedocs hide deploydocs -Documenter.generate -Travis -Travis.genkeys Deps Deps.pip ``` diff --git a/docs/src/man/hosting.md b/docs/src/man/hosting.md index 7c93b7c88c..ee1c1a479d 100644 --- a/docs/src/man/hosting.md +++ b/docs/src/man/hosting.md @@ -41,10 +41,18 @@ 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.jl` package. +DocumenterTools can be added using the Julia package manager. From the REPL, type `]` +to enter the Pkg REPL mode and run + +``` +pkg> add DocumenterTools +``` + +DocumenterTools can now be loaded as ```jlcon -julia> using Documenter +julia> using DocumenterTools ``` Then call the [`Travis.genkeys`](@ref) function as follows: @@ -119,7 +127,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/Documenter.jl b/src/Documenter.jl index a2c8a82b45..dfd0a7c991 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -18,6 +18,14 @@ 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 # ---------- @@ -34,7 +42,6 @@ include("DocChecks.jl") include("Writers/Writers.jl") include("Deps.jl") include("Generator.jl") -include("Travis.jl") import .Utilities: Selectors @@ -42,7 +49,7 @@ import .Utilities: Selectors # User Interface. # --------------- -export Travis, Deps, makedocs, deploydocs, hide +export Deps, makedocs, deploydocs, hide """ makedocs( @@ -591,92 +598,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..bf39e9b138 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -49,9 +49,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