Skip to content

Latest commit

 

History

History
53 lines (36 loc) · 2.94 KB

README.md

File metadata and controls

53 lines (36 loc) · 2.94 KB
Raw

Documentation Publishing

These configurations are for publishing documentation.

GitHub Pages

This configuration uses the gradle-git-publish plugin to publish to GitHub Pages.

This configuration expects your documentation to be in the format generated by the dokka configuration in this repo.

This configuration also expects your GitHub Pages site to use the Android Documentation Theme from the gh-pages-theme branch of this repo.

Setup

1. Add plugin

You first need to add the gradle-git-publish plugin to your root build.gradle.

plugins {
    id 'org.ajoberstar.git-publish' version '2.1.3'
}

2. Create configuration and apply the plugin

Next, you must create the docPublishing configuration object and define the repoUri where the documentation should be published (this must be done before applying the gradle script). This must be the SSH URI (starts with git@).

If you are using CI, your CI must be configured with an SSH key that has write access to the repo. If you are using CircleCI, see the section below How to add Github SSH Key to CircleCI for instructions on how to set this up.

project.ext.docPublishing = [
        repoUri: '[email protected]:ORGANIZATION/REPO_NAME.git'
]
apply from: '../config/publish/documentation/gh-pages.gradle'

This will do the following:

  • Apply the gradle-git-publish plugin plugin. See the plugin documentation for the tasks that are available from this plugin.
  • Setup the gradle-git-publish plugin for publishing the $buildDir/publishableDocs/_versions, and $buildDir/publishableDocs/docs folders to the gh-pages branch or your repoUri.
  • If the project version IS NOT a snapshot (does not contains a -), then add the documentation publishing task as a dependency of the publish task.
  • If the project version IS a a snapshot, then do nothing.

Advanced

How to add Github SSH Key to CircleCI

  1. Generate the private and public key with ssh-keygen -m PEM -t rsa -b 4096 -f ./id_rsa
  2. Copy the contents of the private key (id_rsa).
  3. On the CircleCI settings page for your project, go to the SSH Permissions tab, click Add SSH Key, and paste your private key.
  4. Copy the contents of the public key (id_rsa.pub).
  5. On the settings page for your Github repo, go to Deploy Keys click Add deploy key, and paste your public key. Be sure to also select the Allow write access checkbox.
  6. If you already had a Deploy key which was automatically generated by CircleCI, this should be removed because it only has "read" permissions and CircleCI will try to use it by default. On the CircleCI settings screen, go to the Checkout SSH keys and remove the deploy key.