Project documentation

Warning

This page is now hosted on https://odp.finos.org/docs/project-collaboration#project-website

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:
1. Docusaurus is the most complete and recommended tool to easily manage project documentation on GitHub; is allows to manage content in MarkDown files, configure navigation and sidebars, manage versioning and is highly customizable using React.
2. Hugo, an alternative to Docusaurus that generates static HTML using Go Templates and some predefined conventions
3. Jekyll, a Ruby-based static site generator that is embedded in GitHub Pages; it is highly customisable using variables, custom layouts, HTML blocks
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 the pages 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:

GH_TOKEN
GH_USERNAME
GH_EMAIL

You can setup variables the Travis Repository Settings or with the travis CLI.

.travis.yml

# 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.