<NME> hosting.md
<BEF> ADDFILE
<MSG> Add manual section on automatic docs building/hosting.

<DFF> @@ -0,0 +1,142 @@
+# 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 'cd(Pkg.dir("PACKAGE_NAME")); include(joinpath("docs", "make.jl"))'
+```
+
+## The `deploydocs` Function
+
+At the moment your `docs/make.jl` file probably only contains
+
+```julia
+using Lapidary, PACKAGE_NAME
+
+makedocs()
+```
+
+We'll need to add an additional call to this file after [`makedocs`]({ref}). Add the
+following at the end of the file:
+
+```julia
+deploydocs(
+    repo = "github.com/USER_NAME/PACKAGE_NAME.jl.git"
+)
+```
+
+where `USER_NAME` and `PACKAGE_NAME` must be set to the appropriate names.
+
+## The MkDocs `mkdocs.yml` File
+
+We'll be using [MkDocs](http://www.mkdocs.org) to convert the markdown files generated by
+Lapidary to HTML. (This, of course, is not the only option you have for this step. Any
+markdown to HTML converter should work fine with some amount of setting up.)
+
+Add an `mkdocs.yml` file to your `docs/` directory with the following content:
+
+```yaml
+site_name:        PACKAGE_NAME.jl
+repo_url:         https://github.com/USER_NAME/PACKAGE_NAME.jl
+site_description: Description...
+site_author:      USER_NAME
+
+theme: readthedocs
+
+extra_css:
+  - assets/Lapidary.css
+
+extra_javascript:
+  - https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML
+  - assets/mathjaxhelper.js
+
+markdown_extensions:
+  - extra
+  - tables
+  - fenced_code
+
+docs_dir: 'build'
+
+pages:
+  - Home: index.md
+```
+
+This is only a basic skeleton. Read through the MkDocs documentation if you would like to
+know more about the available settings.
+
+## `.gitignore`
+
+Add the following to your package's `.gitignore` file
+
+```
+docs/build/
+docs/site/
+```
+
+These are needed to avoid committing generated content to your repository.
+
+## `gh-pages` Branch
+
+Create a new branch called `gh-pages` and push it to GitHub. If this branch already exists
+then you can skip this step, but do note that the generated content is automatically pushed
+to this branch from Travis.
+
+---
+
+**Final Remarks**
+
+That should be all that is needed to enable automatic documentation building. Pushing new
+commits to your `master` branch should trigger doc builds. Note that other branches do not
+trigger these builds and neither do pull requests by potential contributors.
+
+If you would like to see a more complete example of how this process is setup then take a
+look at this package's repository for some inspiration.

Add manual section on automatic docs building/hosting.