Publish Angular Library documentation created with Nx using TravisCI and GitHub Pages

This is the second part for a series of posts that will help you to create an Angular 7 publishable library using Nrwl Nx Angular Extensions.

Nrwl Extensions for Angular

This article covers the following things:

• Setup of GitHub pages
• Setup of Travis CI
• Extra — Install compodoc to enhance documentation

Here are the links for all the parts of this series:

Part 1. Creating an Angular library with Nrwl Nx

Part 2. Publish Angular Library documentation created with Nx using TravisCI and GitHub Pages

Part 3. Publish Angular Library created with Nx to NPM

Part 4. Generating Changelog file for an Angular library

Setup GitHub Pages

GitHub Pages

Let's start by enabling GitHub Pages on the library repository.

Go to your repository under GitHub and in the setting pages you will find a section to configure the GitHub Pages.blue

Make sure to use the gh-pages branch and ‘Enforce HTTPS’ as you can see below:

Set up Travis

Travis CI - Test and Deploy Your Code with Confidence

1. Add a .travis.yml file to the root of your project with the following configuration:

// .travis.yml
language: node_js
node_js:
   - '9'
dist: trusty
sudo: required
branches:
only:
  - master
before_script:
  - npm install -g @angular/cli
script:
  - ng build --prod --base-href https://alfredoperez.github.io/ngx-datacontext/
deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  local_dir: dist/apps/documentation/
  on:
    branch: master

Let me go briefly on what this file is doing.

To build the application on Travis CI it needs to have the Angular CLI and that’s accomplished with this:

// .travis.yml
...
before_script:
- npm install -g @angular/cli

After this, it will execute the build command from the CLI, but setting the href to where it should be deployed using the name of the repository. In my case, I am deploying the repository under ‘ngx-datacontext’

// .travis.yml
...
script:
- ng build --prod --base-href https://alfredoperez.github.io/ngx-datacontext/

2. Push file to Github repository, because Travis CI will need it while deploying.

3. Create an account at https://travis-ci.org/, link it to your GitHub account and enable it for the library repository.

3. Add a Github token to deploy from Travis to the Github pages. To do this, first, modify the deploy section on the travis.yml to include a variable for the token.

// .travis.yml
...
deploy: 
 provider: pages 
 skip_cleanup: true 
 github_token: $GITHUB_TOKEN 
 local_dir: dist/apps/documentation/ 
 on: 
   branch: master

4. Create a Github personal access token following the instruction from:

Creating a personal access token for the command line - User Documentation

5. Add the token to the settings under Travis CI

Try Out Travis CI and Github Pages!

This is all that is needed to enable the deployment to Github Pages using Travis CI.

Travis will trigger a deployment everytime a commit gets pushed to the library repository and the documentation website will be hosted under Github Pages.

— EXTRA — Add Compodoc documentation

As an extra, I want to go through the process of adding compodoc to enhance the Angular library documentation.

Compodoc - The missing documentation tool for your Angular application

1. Install compodoc

yarn add @compodoc/compodoc

2. Add scripts to execute compodoc at the package.json

Note: The path is to the tsconfig from the library used to generate documentation

// package.json
...
"build:doc": "./node_modules/.bin/compodoc
             -p libs/core/tsconfig.lib.json
             --theme Readthedocs 
             -d dist/apps/documentation/compodoc ",
"serve:doc": "./node_modules/.bin/compodoc 
              -p libs/core/tsconfig.lib.json 
              --theme Readthedocs 
              -d dist/apps/documentation/compodoc
              -s",

3. Add a link to the compodoc index.html

<a href="compodoc/index.html" target="_blank">
 Documentation
</a>

4. Add the script to .travis.yml configuration

// .travis.yml
...
script:
  - ng build --prod --base-href https://alfredoperez.github.io/ngx-datacontext/
  - npm run build:doc

Try it out!

Here is an example of Github page deployed with Travis:

https://alfredoperez.github.io/ngx-datacontext/