<commit_before># Hosting Documentation

After going through the [Package Guide]({ref}) and [Doctests]({ref}) page you will need to
host the generated documentation somewhere for potential users to read. This guide will
describe how to setup automatic updates for your package docs using the Travis build service
and GitHub Pages. This is the same approach used by this package to host it's own docs --
the docs you're currently reading.

**Note**

This guide assumes that you already have GitHub and Travis accounts setup. If not then go
set those up first and then return here.

## Overview

Once setup correctly the following will happen each time you push new updates to your
package repository:

- travis buildbots startup and run your tests;
- each buildbot will build the package docs using your `docs/make.jl` script;
- a single buildbot will then try to push the generated docs back the github.

The following sections outline how to enable this for your own package.

## GitHub Security Key

Firstly, generate a new [personal access token](https://github.com/settings/tokens).

Enter a description for this new token. We'll be calling ours "Travis", but any other name
will do. For the "Select scopes" option choose "public_repo" **only**. Then generate the
token and save it somewhere safe. We'll be needing it during the next section.

## Travis Environment Settings

Next we'll add the generated token to our repository's Travis page. Go to the settings page
for the repository and under the "Environment Variables" section add a new variable called
`GITHUB_API_KEY`. Copy the generated key from the [GitHub Security Key]({ref}) section as
the value and **make sure** that "Display value in build log" is **off**. Then add the key.

## `.travis.yml` Configuration

To allow Travis to install the extra dependencies needed to build our docs add the following
to your `.travis.yml` file in your package:

```yaml
before_script:
  - export PATH=$HOME/.local/bin:$PATH
```

In the `after_success` section of the `.travis.yml` file, where code coverage is processed,
run your `docs/make.jl` file:

```yaml
after_success:
  - julia -e 'Pkg.clone("https://github.com/MichaelHatherly/Lapidary.jl")'
  - julia -e 'cd(Pkg.dir("PACKAGE_NAME")); include(joinpath("docs", "make.jl"))'
```<commit_msg>Added comment about leading white-space in api key<commit_after># Hosting Documentation

After going through the [Package Guide]({ref}) and [Doctests]({ref}) page you will need to
host the generated documentation somewhere for potential users to read. This guide will
describe how to setup automatic updates for your package docs using the Travis build service
and GitHub Pages. This is the same approach used by this package to host it's own docs --
the docs you're currently reading.

**Note**

This guide assumes that you already have GitHub and Travis accounts setup. If not then go
set those up first and then return here.

## Overview

Once setup correctly the following will happen each time you push new updates to your
package repository:

- travis buildbots startup and run your tests;
- each buildbot will build the package docs using your `docs/make.jl` script;
- a single buildbot will then try to push the generated docs back the github.

The following sections outline how to enable this for your own package.

## GitHub Security Key

Firstly, generate a new [personal access token](https://github.com/settings/tokens).

Enter a description for this new token. We'll be calling ours "Travis", but any other name
will do. For the "Select scopes" option choose "public_repo" **only**. Then generate the
token and save it somewhere safe. We'll be needing it during the next section.

## Travis Environment Settings

Next we'll add the generated token to our repository's Travis page. Go to the settings page
for the repository and under the "Environment Variables" section add a new variable called
`GITHUB_API_KEY`. Copy the generated key from the [GitHub Security Key]({ref}) section as
the value and **make sure** that "Display value in build log" is **off**. Be careful to remove any leading white-space from the key. Then add the key.

## `.travis.yml` Configuration

To allow Travis to install the extra dependencies needed to build our docs add the following
to your `.travis.yml` file in your package:

```yaml
before_script:
  - export PATH=$HOME/.local/bin:$PATH
```

In the `after_success` section of the `.travis.yml` file, where code coverage is processed,
run your `docs/make.jl` file:

```yaml
after_success:
  - julia -e 'Pkg.clone("https://github.com/MichaelHatherly/Lapidary.jl")'
  - julia -e 'cd(Pkg.dir("PACKAGE_NAME")); include(joinpath("docs", "make.jl"))'
```
{'fraction_non_alphanumeric': 0.08031529612270984, 'fraction_numerical': 0.0, 'mean_word_length': 4.543093270365998, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1037191', 'n_tokens_mistral': 1303, 'n_tokens_neox': 1228, 'n_words': 665}