ddox on Travis CI

howto.md

Serve ddox documentation on github.io deployed by Travis CI

This guide makes no assumptions on prior knowledge of Github Pages or Travis CI. You'll know which steps to skip (if the project uses Pages already, this will overwrite them). Assumed is you have a public D project on GitHub and you have documented its API with embedded ddoc comments. You should probably be aware of the known issues of ddox, which we use here.

For a project URL like https://github.com/<user>/<project>, the documentation will appear at https://<user>.github.io/<project>/.

Enable Travis CI for your repository

The long story: https://docs.travis-ci.com/user/getting-started/, https://docs.travis-ci.com/user/languages/d/

The short story:

1. Using your GitHub account, sign in to https://travis-ci.org/ and accept the GitHub access permissions confirmation.
2. Travis CI will synchronize with your GitHub repositories, which will show up in your profile page at https://travis-ci.org/profile/<user>. Press the Sync account button when necessary. Flip the switch that corresponds to the project in question.
3. Add a basic .travis.yml file to the root of your repository with the content below and push it to GitHub, or add it online at https://github.com/<user>/<project>/new/master.

language: d

When you go to https://travis-ci.org/<user>/<project> you'll see your unit tests being run.

Allow Travis CI to push to your repository

The long story: https://gist.github.com/vidavidorra/548ffbcdae99d752da02#provide-travis-ci-with-encrypted-credentials-for-publishing-to-gh-pages

The short story:

1. Install the travis client. (If you don't like this step, you can find a web-based alternative in the link above; albeit less secure.)
2. Go to https://github.com/settings/tokens and press Generate new token.
3. Fill in the description, e.g., <project> Travis CI Documentation.
4. Select the single scope
   • public_repo
5. Press the Generate token button.
6. Copy the new token string now.
7. In your repository directory (where .travis.yml is), run:

   travis encrypt --org --add --repo <user>/<project> GH_REPO_TOKEN=<copied_personal_acces_github_token>
   

   This will add the encypted token to .travis.yml.

Build and deploy the documentation

Append the following to your .travis.yml file:

# This will run on Travis' 'new' container-based infrastructure
sudo: false

# Do nothing for branches and PRs
branches:
  only:
    - master

# Ddox dependencies
addons:
  apt:
    packages:
      - libevent-dev

# Build steps
script:
#  - dub test --compiler=${DC}  # If you want to run unittests
   - dub build -b ddox

# Deploy using travis builtin GitHub Pages support
deploy:
  provider: pages
  skip_cleanup: true
  local_dir: $TRAVIS_BUILD_DIR/docs
  github_token: $GH_REPO_TOKEN
  on:
    branch: master

and push to GitHub. This will trigger a build on Travis CI. Once it's done, visit https://<user>.github.io/<project>/ and admire your online documentation!

Dotting your i's

Insert the following into your dub.json file (or the equivalent into dub.sdl):

	"-ddoxFilterArgs": [
		"--unittest-examples",
		"--min-protection=Protected"
	],
	"-ddoxTool": "scod"

This will:

1. convert unittests prepended with /// into examples in the documentation
2. exclude private API
3. Use the scod theme.

Expanding

Have a look at bloom for an example of how to do more.

---

Bastiaan Veelo

License: Boost