Skip to content

Commit

Permalink
WIP remove Travis.genkeys and Documenter.generate to new package Docu…
Browse files Browse the repository at this point in the history 
…menterTools
  • Loading branch information
@fredrikekre
fredrikekre committed Aug 10, 2018
1 parent 5f470a0 commit 4f89864
Show file tree
Hide file tree
Showing 6 changed files with 12 additions and 275 deletions.
2 changes: 0 additions & 2 deletions docs/src/lib/public.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,6 @@ makedocs
hide
deploydocs
Documenter.generate
Travis
Travis.genkeys
Deps
Deps.pip
```
61 changes: 5 additions & 56 deletions docs/src/man/hosting.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
96 changes: 7 additions & 89 deletions src/Documenter.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down Expand Up @@ -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 `<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
Base.@deprecate_moved generate "DocumenterTools" false

end
95 changes: 0 additions & 95 deletions src/Travis.jl
View file
Original file line number Diff line number Diff line change
@@ -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
30 changes: 0 additions & 30 deletions test/generate.jl
View file

This file was deleted.

3 changes: 0 additions & 3 deletions test/runtests.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 4f89864

Please sign in to comment.