Sources of the ATS Garage and HERE dev portal docsite
Branch: stable
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
_compass
_data
_includes
_layouts
_pages
_posts
bin
css
design
favicon
files
fonts
images
js
.gitignore
Gemfile
README.adoc
_config.yml
_secrets.yml.example
build.sh
error.adoc
index.ad
publish-here.sh
publish.sh
s3_credentials.env.example

README.adoc

ATS Garage Docsite

This is the source for docs.atsgarage.com and for the HERE Developer Portal docs for HERE OTA Connect. It’s built with Jekyll, a static site generator.

The text is written in Asciidoc, and rendered by Asciidoctor. Asciidoctor exercises a large number of styles, and has a tool to build stylesheets called asciidoctor-stylesheet-factory. However, that’s pretty much just a compass pipeline, so we added it to our jekyll build process (to eliminate some annoying steps). See ` _compass` for all those details.

Configuration

Building the site requires a github access token with access to ATS private repos. Pushing the site to docs.atsgargae.com requires a set of AWS IAM credentials with access to the docs.ota.here.com S3 bucket. Pushing to the dev portal requires push access to https://gerrit.it.here.com/#/admin/projects/DOCS/ota_update_platform.

Github token

  1. Generate the token.

  2. Copy ` _secrets.yml.example` to ` _secrets.yml`, substituting your token.

AWS credentials

  1. Get the docs IAM credentials from the Infra team.

  2. copy s3_credentials.env.example to s3_credentials.env, substituting the real credentials.

Build

Build the site with Docker:

./build.sh

Build the site from a local jekyll install:

bundle install
jekyll build --config _config.yml,_secrets.yml

Publish

Publish to the web:

./publish.sh <staging|prod|docs-ats>

Publish HTML assets to the internal HERE docs repo:

./publish-here.sh <gerrit_username>

Debugging

If you’re having issues with how jekyll is rendering the site, you can add debug breakpoints to any of the layouts or includes with a {% debug %} liquid tag. See the debugger docs at https://github.com/octopress/debugger.

If it’s a problem that only affects a single page, you can set the layout of that page to 'debug'.

Navigation

The sidebar navigation can be customized in ` _config.yml`. The sections key lists the sections that will appear in the navigation, and the navigation_tabs key lists the tabs, and which sections each one contains. (Details in the yaml comments.)

Multiple-language code tabs/code samples

You can make codetabs appear by using asciidoc attributes. Just put multiple source blocks, give one of them the "primary" role, and the others "secondary". Make sure to give each block a name; that’s what will be used for the title of the tab. Example:

[source,C,role="primary"]
.C (ANSI)
----
/* Hello World in C, Ansi-style */

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
  puts("Hello World!");
  return EXIT_SUCCESS;
}
----

[source,python,role="secondary"]
.Python
----
print("Hello World")
----

[source,python,role="secondary"]
.link:https://esolangs.org/wiki/Ook![Ook]
----
Ook. Ook? Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook.
Ook. Ook. Ook. Ook. Ook! Ook? Ook? Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook.
Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook? Ook! Ook! Ook? Ook! Ook? Ook.
Ook! Ook. Ook. Ook? Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook.
Ook. Ook. Ook! Ook? Ook? Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook?
Ook! Ook! Ook? Ook! Ook? Ook. Ook. Ook. Ook! Ook. Ook. Ook. Ook. Ook. Ook. Ook.
Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook! Ook. Ook! Ook. Ook. Ook. Ook. Ook.
Ook. Ook. Ook! Ook. Ook. Ook? Ook. Ook? Ook. Ook? Ook. Ook. Ook. Ook. Ook. Ook.
Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook! Ook? Ook? Ook. Ook. Ook.
Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook? Ook! Ook! Ook? Ook! Ook? Ook. Ook! Ook.
Ook. Ook? Ook. Ook? Ook. Ook? Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook.
Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook! Ook? Ook? Ook. Ook. Ook.
Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook.
Ook. Ook? Ook! Ook! Ook? Ook! Ook? Ook. Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook.
Ook? Ook. Ook? Ook. Ook? Ook. Ook? Ook. Ook! Ook. Ook. Ook. Ook. Ook. Ook. Ook.
Ook! Ook. Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook.
Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook! Ook!
Ook! Ook. Ook. Ook? Ook. Ook? Ook. Ook. Ook! Ook. Ook! Ook? Ook! Ook! Ook? Ook!
Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook.
Ook. Ook. Ook. Ook. Ook! Ook.
----

Contextual help in app

The web app needs some contextual help pages. Since that’s documentation, we want to keep the single source of truth here in the docs repo. We accomplish this by writing the contextual help pages in asciidoc (using include::[] statements as liberally as possible). For each contextual help page, do the following:

  1. Create a new jekyll page with the category context_help:

    ./bin/jekyll-page "My page title" context_help
  2. Change the :page_layout: to context_help to make it render as raw HTML without the navigation, etc.

  3. Write your doc.

  4. It will render in the static site under /context_help/page-name-slug.html when the site is built.