Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Misc doc changes related to recent code changes #1156

Merged
merged 1 commit into from
Oct 9, 2019
Merged

Misc doc changes related to recent code changes #1156

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 14 additions & 11 deletions docs/src/man/hosting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,8 @@ 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 the builder to GitHub. The SSH keys can be generated with the
`genkeys` from the [DocumenterTools](https://github.com/JuliaDocs/DocumenterTools.jl)
package.
generated documentation from the builder to GitHub. The SSH keys can be generated with
`DocumenterTools.genkeys` from the [DocumenterTools](https://github.com/JuliaDocs/DocumenterTools.jl) package.

!!! note

Expand Down Expand Up @@ -86,13 +85,15 @@ where `MyPackage` is the package you would like to create deploy keys for. The o
look similar to the text below:

```
INFO: add the public key below to https://github.com/USER/REPO/settings/keys
[ 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.com/USER/REPO/settings with value:
[ Info: add a secure environment variable named 'DOCUMENTER_KEY' to
https://travis-ci.com/USER/REPO/settings (if you deploy using Travis CI) or
https://github.com/USER/REPO/settings/secrets (if you deploy using GitHub Actions)
with value:

[LONG BASE64 ENCODED PRIVATE KEY]
```
Expand All @@ -105,14 +106,15 @@ Follow the instructions that are printed out, namely:
**`Key`** field. 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
2. Next add the long private key to the Travis/GitHub Actions 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
To reiterate: make sure that this key is hidden. In particular, in the Travis CI settings
the "Display value in build log" option should be **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
Expand Down Expand Up @@ -349,8 +351,9 @@ look at this package's repository for some inspiration.
It is possible to customize Documenter to use other systems then the ones described in
the sections above. This is done by passing a configuration
(a [`DeployConfig`](@ref Documenter.DeployConfig)) to `deploydocs` by the `deploy_config`
keyword argument. Currently, only [`Travis`](@ref Documenter.Travis) is implemented, but it
is easy to define your own by following the simple interface described below.
keyword argument. Documenter natively supports [`Travis`](@ref Documenter.Travis) and
[`GitHubActions`](@ref Documenter.GitHubActions) natively, but it is easy to define
your own by following the simple interface described below.

```@docs
Documenter.DeployConfig
Expand Down
28 changes: 18 additions & 10 deletions docs/src/man/hosting/walkthrough.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ process. There are three main steps:

1. [Generating an SSH Key](@ref)
2. [Adding the Public Key to GitHub](@ref)
3. [Adding the Private Key to Travis](@ref)
3. [Adding the Private Key](@ref)

## Generating an SSH Key

Expand All @@ -30,7 +30,7 @@ And the private key usually look something like this

### If you have `ssh-keygen` installed

If you have `ssh-keygen` installed, but `Travis.genkeys()` didn't work, you can generate an
If you have `ssh-keygen` installed, but `DocumenterTools.genkeys()` didn't work, you can generate an
SSH key as follows. First, generate a key using `ssh-keygen` and save it to the file
`privatekey`:

Expand All @@ -46,8 +46,7 @@ julia> using Base64
julia> read("privatekey", String) |> base64encode |> println
```

Copy and paste the output somewhere. This is your *private key* and is required for the step
[Adding the Private Key to Travis](@ref).
Copy and paste the output somewhere. This is your *private key* and is required for the last step.

Now we need to get the public key. Run the following command:

Expand Down Expand Up @@ -89,8 +88,7 @@ Now we need to save the public key somewhere.
Finally, we need to save the private key somewhere.

* Click the "Conversions" tab, and then click "Export OpenSSH key". Save that file
somewhere. That file is your *private key* and is required for the [Adding the Private Key
to Travis](@ref) step.
somewhere. That file is your *private key* and is required for the last step.

![](puttygen-export-private-key.png)

Expand Down Expand Up @@ -123,12 +121,13 @@ Now we need to fill in three pieces of information.
3. Make sure that the "Allow write access" box is checked.

Once you're done, click "Add key". Congratulations! You've added the public key
to GitHub. The next step is to add the private key to Travis.
to GitHub. The next step is to add the private key to Travis or GitHub Secrets.


## Adding the Private Key to Travis
## Adding the Private Key

In this section, we explain how to upload a private SSH key to Travis. By this point, you
In this section, we explain how to upload a private SSH key to Travis or GitHub Actions,
depending on which service you will use for deploying your documentation. By this point, you
should have generated a private key and saved it to a file. If you haven't done this, go
read [Generating an SSH Key](@ref).

Expand All @@ -142,7 +141,9 @@ julia> read("path/to/private/key", String) |> base64encode |> println

Copy the resulting output.

Next, go to `https://travis-ci.com/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings`. Scroll down
### Adding the Private Key to Travis

Go to `https://travis-ci.com/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings`. Scroll down
to the "Environment Variables" section. It should look like this:

![](travis-variables.png)
Expand All @@ -162,6 +163,13 @@ Congratulations! You've added the private key to Travis.
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).


### Adding the Private Key to GitHub Secrets

Go to `https://github.com/USER/REPO/settings/secrets` and press `Add new secret`.
Use `DOCUMENTER_KEY` for the name, and the Base64 encoded key from the previous section
as the value.

---

**Final Remarks**
Expand Down