Hosting Documentation
After going through the Package Guide and Doctests 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
Following this guide should be the final step you take after you are comfortable with the syntax and build process used by Documenter.jl
. Only proceed with the steps outlined on this page once you have successfully used mkdocs
locally to build your documentation. mkdocs
can typically be installed using pip install mkdocs
in your terminal.
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 to github.
Note that the hosted documentation does not update when you make pull requests; you see updates only when you merge to master
or push new tags.
The following sections outline how to enable this for your own package.
Deploy Keys
Two methods are available for securely deploying generated documentation from Travis to GitHub. The first method listed below is the preferred approach. The second, and original, method should be avoided whenever possible.
SSH Deploy Keys
Deploy keys provide push access to a single repository.
Note
You will need several command line programs installed for the following steps to work. They are which
, git
, ssh-keygen
, and travis
. Make sure these are installed before you begin.
Open a Julia REPL and import Documenter
.
julia> using Documenter
Then call the Travis.genkeys
function as follows:
julia> Travis.genkeys("MyPackage")
where "MyPackage"
is the name of the package you would like to create deploy keys for.
You may be asked to enter your password for Travis during this process. Once complete you will need to add the public key displayed in the REPL to your repository – just follow the instructions displayed in the REPL. If you see a line about adding an openssl
command to your .travis.yml
file, you can ignore that (Documenter will handle that for you).
Then close the REPL and commit the docs/.documenter.enc
file that was generated by Travis.genkeys
to the repository. You can skip the GitHub Security Tokens section and move straight on to Travis Environment Settings now.
If you don't get a docs/.documenter.enc
file, one possible reason is an outdated version of travis
. At the time of this writing, version 1.8.2 was known to work.
GitHub Security Tokens
These tokens provide push access to every repository owned by the user.
Firstly, generate a new personal access token.
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
SSH Keys
If you used Travis.genkeys
in the previous step then you should go to your Travis settings page and check that two new keys have been added with names similar to the following
encrypted_e6b49e69746a_key
encrypted_e6b49e69746a_iv
Tokens
If you generated a GitHub token during the previous step then we'll add the 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 Tokens 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
In the after_success
section of the .travis.yml
file, where code coverage is processed, run your docs/make.jl
file:
after_success: - julia -e 'Pkg.add("Documenter")' - 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
using Documenter, PACKAGE_NAME makedocs()
We'll need to add an additional call to this file after makedocs
. Add the following at the end of the file:
deploydocs( repo = "github.com/USER_NAME/PACKAGE_NAME.jl.git" )
where USER_NAME
and PACKAGE_NAME
must be set to the appropriate names.
By default deploydocs
will deploy the documentation from the nightly
Julia build for Linux. This can be changed using the julia
and osname
keywords as follows:
deploydocs( deps = Deps.pip("mkdocs", "python-markdown-math"), repo = "github.com/USER_NAME/PACKAGE_NAME.jl.git", julia = "0.4", osname = "osx" )
This will deploy the docs from the OSX Julia 0.4 Travis build bot.
The keyword deps
serves to provide the required dependencies to deploy the documentation. In the example above we include the dependencies mkdocs and python-markdown-math
. The former makes sure that MkDocs is installed to deploy the documentation, and the latter provides the mdx_math
markdown extension to exploit MathJax rendering of latex equations in markdown. Other dependencies should be included here.
See the deploydocs
function documentation for more details.
The MkDocs mkdocs.yml
File
We'll be using MkDocs to convert the markdown files generated by Documenter 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:
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/Documenter.css extra_javascript: - https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML - assets/mathjaxhelper.js markdown_extensions: - extra - tables - fenced_code - mdx_math 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.
Documentation Versions
When documentation is generated it is stored in one of the following folders:
latest
stores the most recent documentation that is committed to themaster
branch.stable
stores the most recent documentation from a tagged commit. Older tagged versions are stored in directories named after their tags. These tagged directories are persistent and must be manually removed from thegh-pages
branch if necessary.
Once your documentation has been pushed to the gh-pages
branch you should add links to your README.md
pointing to the stable
and latest
documentation URLs. It is common practice to make use of "badges" similar to those used for Travis and AppVeyor build statuses or code coverage. Adding the following to your package README.md
should be all that is necessary:
[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://USER_NAME.github.io/PACKAGE_NAME.jl/stable) [![](https://img.shields.io/badge/docs-latest-blue.svg)](https://USER_NAME.github.io/PACKAGE_NAME.jl/latest)
PACKAGE_NAME
and USER_NAME
should be replaced with their appropriate values. The colour and text of the image can be changed by altering docs-stable-blue
as described on shields.io, though it is recommended that package authors follow this standard to make it easier for potential users to find documentation links across multiple package README files.
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.