diff --git a/docs/src/lib/public.md b/docs/src/lib/public.md index 37c65e4e096..4400cb83ab2 100644 --- a/docs/src/lib/public.md +++ b/docs/src/lib/public.md @@ -24,8 +24,6 @@ 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 7c93b7c88c6..5bdd37047a4 100644 --- a/docs/src/man/hosting.md +++ b/docs/src/man/hosting.md @@ -33,63 +33,12 @@ The following sections outline how to enable this for your own package. ## SSH Deploy Keys -Deploy keys provide push access to a *single* repository, to allow secure deployment of generated documentation from Travis to GitHub. +Deploy keys provide push access to a *single* repository, to allow secure deployment of generated documentation from Travis to GitHub. The `DocumenterTools` package provides a function, +`DocumenterTools.Travis.genkeys` that generate a set of SSH keys. -!!! note - - You will need several command line programs installed for the following steps to work. - 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). - -```jlcon -julia> using Documenter -``` - -Then call the [`Travis.genkeys`](@ref) function as follows: - -```jlcon -julia> Travis.genkeys("MyPackage") -``` - -where `"MyPackage"` is the name of the package you would like to create deploy keys for. The -output will look similar to the text below: - -``` -INFO: add the public key below to https://github.com/USER/REPO/settings/keys - with read/write access: - -[SSH PUBLIC KEY HERE] - -INFO: add a secure environment variable named 'DOCUMENTER_KEY' to - https://travis-ci.org/USER/REPO/settings with value: - -[LONG BASE64 ENCODED PRIVATE KEY] -``` - -Follow the instructions that are printed out, namely: - - 1. Add the public ssh key to your settings page for the GitHub repository that you are - setting up by following the `.../settings/key` link provided. Click on **`Add deploy - key`**, enter the name **`documenter`** as the title, and copy the public key into the - **`Key`** field. Note that you should include **no whitespace** when copying the key. - Check **`Allow write access`** to allow Documenter to commit the generated documentation - to the repo. - - 2. Next add the long private key to the Travis settings page using the provided link. Again - note that you should include **no whitespace** when copying the key. In the **`Environment - Variables`** section add a key with the name `DOCUMENTER_KEY` and the value that was printed - out. **Do not** set the variable to be displayed in the build log. Then click **`Add`**. - - !!! warning "Security warning" - - To reiterate: make sure that the "Display value in build log" option is **OFF** for - the variable, so that it does not get printed when the tests run. This - base64-encoded string contains the *unencrypted* private key that gives full write - access to your repository, so it must be kept safe. Also, make sure that you never - expose this variable in your tests, nor merge any code that does. You can read more - about Travis environment variables in [Travis User Documentation](https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings). +!!! warning + Read the `DocumenterTools` documentation carefully. SSH keys give push access + to the repository, and should be handled with care. ## `.travis.yml` Configuration diff --git a/src/Documenter.jl b/src/Documenter.jl index d1e3c28ee31..f1b2a15ac8a 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -51,13 +51,17 @@ include("DocChecks.jl") include("Writers/Writers.jl") include("Deps.jl") include("Generator.jl") -include("Travis.jl") + +module Travis + Base.@deprecate_moved genkeys "DocumenterTools" false +end # module +export Travis # User Interface. # --------------- -export Travis, Deps, makedocs, deploydocs, hide +export Deps, makedocs, deploydocs, hide """ makedocs( @@ -606,92 +610,6 @@ 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 +Base.@deprecate_moved generate "DocumenterTools" false end diff --git a/src/Travis.jl b/src/Travis.jl index c70bb81db90..8b137891791 100644 --- a/src/Travis.jl +++ b/src/Travis.jl @@ -1,96 +1 @@ -""" -Package functions for interacting with Travis. -$(EXPORTS) -""" -module Travis - -using Compat, DocStringExtensions -import Compat.Pkg -import Compat.Base64: base64encode - -export genkeys - -import Compat.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" - Compat.@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" - Compat.@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 53c4ab3e313..00000000000 --- a/test/generate.jl +++ /dev/null @@ -1,30 +0,0 @@ -module GenerateTests - -using Compat.Test -import Compat.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 d60c90fcad3..7335ed26247 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -50,9 +50,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