Managing ACS documentation

ACS documentation is built with Jekyll static-site generator and hosted on GitHub Pages. ACS documentation is publicly available at https://ncar.github.io/ACS/

Jekyll

Jekyll is provided by a Ruby Gem. Installation instructions are available on the Jekyll website: https://jekyllrb.com/docs/installation/

The root of ACS documentation is the docs/ directory. Subsequent commands are assumed to be invoked from there, unless otherwise specified.

cd docs

Jekyll is configured in _config.yml. For complete details on configuring Jekyll, see https://jekyllrb.com/docs/configuration/

The site layout provides the theme and ‘wrapper’ to the documentation content and is managed in _layouts/default.html.

CSS theming is provided by the Bootstrap framework. This is configured in _includes/head.html, which loads https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css.

jekyll serve

Site content is provided by Markdown files in pages/

Site content can be dynamically viewed by running

jekyll serve

And loading the site in the browser via http://localhost:4000

jekyll build

The site can be built by running

jekyll build

Which will build a static site into _site/

The static site can be browsed via:

jekyll exclude

By design, Jekyll publishes everything in docs/ to the static website. When used with GitHub Pages, this means that internal files in docs/, such as build scripts and Gemfile, will be publicly available, although there won’t be any links to these files. To avoid publishing unintended files, the exclude key in the Jekyll configuration file, _config.yml can be used to specify files and directories that should be excluded.

  • https://jekyllrb.com/docs/configuration/options/
  • https://idratherbewriting.com/documentation-theme-jekyll/mydoc_exluding_files.html

To check if unintended files are being published, jekyll build can be run, followed by examining _site/ to verify that it only contains the intended files, eg. HTML, JavaScript and image files.

GitHub Pages

GitHub Pages supports Jekyll and automatically builds the site from docs/ when changes are pushed or merged to the master branch for the ACS repository at GitHub.

API documentation

API documentation is provided by Raml. The API documentation is stored as .raml files in pages/api. The raml2html utility compiles the .raml files to html.

The root of the API documentation is (docs/)pages/api. Subsequent commands are assumed to be invoked from there, unless otherwise specified.

cd pages/api

raml2html is provided by an npm package, raml2html. It and the markdown-theme dependency can be installed via:

npm i raml2html raml2html-markdown-theme

A Makefile provides a task for conveniently building a Markdown file of the API documentation, api-rest.md:

make hack

Home page

The home page of the site is provided by (docs)/index.md

Table of Contents

Table of Contents are dynamically displayed for each page unless the page is configured with toc: false, e.g.

toc: false

The html for the Table of Contents is provided by _includes/toc.html

Site navigation is currently provided via two means:

  • top-navigation menu
  • side bar

When new pages are added, the respective configurations should be updated to include the new pages.

Top Navigation

Top navigation is specified via assigning a value to topnav in Front Matter. This is currently primarily done by assigning a value for Front Matter defaults in _config.yml, e.g.

defaults:
  -
    scope:
      path: ""
      type: "pages"
    values:
      topnav: topnav

For the value topnav, top navigation is then configured via _data/topnav.yml. It is accessed through a ‘hamburger button’ menu at the top of the page. The html for top navigation is provided by _includes/topnav.html.

The side bar is specified via assigning a value to sidebar in Front Matter. This is currently primarily done by assigning a value for Front Matter defaults in _config.yml, e.g.

defaults:
  -
    scope:
      path: ""
      type: "pages"
    values:
      sidebar: acs_sidebar

The specified side bar should correspond to a value listed under sidebars:

sidebars:
  - acs_sidebar

For the value acs_sidebar, the side bar is configured via _data/sidebars/acs_sidebar.yml. The html for acs_sidebar is provided by _includes/sidebar.html and the Navgoco jQuery plugin enables dynamic behavior of the sidebar.