There are different ways documentation can be written and published within FINOS.
GitHub and Markdown, probably the simplest and most intuitive approach: every file written in MarkDown format and hosted in GitHub is automatically parsed and visualised by GitHub; the README.md file located at the root of a project directory is parsed in the GitHub project homepage, which is now a well established best practice to guide consumers to get started with a project. Read more on GitHub Readme doc page
GitHub Wiki is a service that is available for every GitHub repository; it can be enabled/disabled via the GitHub repository settings and provides a dedicated Git endpoint that can host Markdown files and generates its web version.
GitHub Pages, to customise the look 'n feel of the page and publish the HTML version of your project docs in a custom domain name (ie myproject.com), yet keeping Markdown as documentation language and GitHub as hosting system; GitHub Pages basically reads HTML and Markdown files from a specific repository folder or branch (configured via GitHub repo settings) onto an HTTP endpoint; finos.github.io is a basic example of GitHub Pages, which uses plain HTML (and Javascript) to build the website, but alternative interpreters can be plugged into GitHub Pages, such as:
Atlassian Confluence can be used for any FINOS Program activity; each program has a dedicated Confluence Space (see the full list), where sub-pages can be created to host activity-specific documentation.
Setting up GitHub Pages
The only setup needed is to tell GitHub where to read the documentation sources from; the suggested option is to use the gh-pages branch, for the following reasons:
Most of the times, documentation must be partially generated (from source code) and sometimes patched before being published; generated content should not live in the same place as source code, to avoid frequent downstream updates to local developers repositories
gh-pages is a branch that is normally used exclusively for this purpose
Travis CI provides thepages deployer that works out of the box, see below
Setting up Travis CI
Simply create a .travis.yml file in the root folder of the repository and follow Travis documentation, according to the adopted languages.
The following environment variables will be needed, in order to run GitHub Pages deployments:
# Configure Travis CI integration with Github Pages - https://docs.travis-ci.com/user/deployment/pages/
deploy:
provider: pages
skip_cleanup: true
github_token: $GH_TOKEN
name: $GH_USERNAME
email: $GH_EMAIL
local_dir: docs
target_branch: gh-pages
on:
branch: master
In order to automate the build, Travis CI must be configured with a GitHub Personal API (or access) Token, also described below as GIT_TOKEN environment variable.