Skip to content

Latest commit

 

History

History
158 lines (105 loc) · 9.95 KB

README.adoc

File metadata and controls

158 lines (105 loc) · 9.95 KB

Build status

GBIF Technical Documentation

The development site is visible at https://techdocs.gbif-uat.org/

Note
This file is documenting the documentation system, it’s not shown on https://techdocs.gbif.org/.

Overall structure

The document system uses Antora, a framework for combining documentation written in Asciidoctor from multiple Git repositories into a single documentation website.

Languages, components, versions and modules

Antora strictly defines how files and directories should be arranged, but is flexible in allowing those files and directories to come from various sources. There are four levels of content:

Languages

(GBIF addition, but following the suggestion on the Antora issue tracker). We don’t expect all the manual to be translated into every language, so we should structure content to make it easy for translators to translate (and see progress) for suitable topics without being overwhelmed.

Components

The largest blocks of documentation. Components we have include Data Publishing and the API reference.

Versions

Each component can optionally have one or more versions. We should only declare versions where it makes sense to keep documentation for the old version accessible online.

Modules

Antora describes modules as "primarily an organization tool for the writer". So far we haven’t used them, so everything is using the default ROOT module.

Each language has its own playbook. Each playbook specifies which components and versions are part of the documentation. See tech-docs-en-playbook.yml for the English playbook. The content.sources with a url of . are in this Git repository, and HEAD shows the current (i.e. main) branch is used to provide a single version. The other components ([email protected]) are from other Git repositories, and some have multiple versions shown in branches.

Determining how individual pages should be arranged into components (and potentially modules) is not clear. It may make translators' work easier if they can aim to translate entire components/modules.

Within a component version

A version of a component is defined by its antora.yml descriptor file, which should be present at the location specified in {url}/{start_path} from the playbook’s content.sources section. For example, the Data Publishing component has its descriptor file in this repository at en/data-publishing/antora.yml:

name: data-publishing
title: Data Publishing
version: ~
nav:
- modules/ROOT/nav.adoc

The name is the identifier for the component used in links and URLs. The title is used for display. A version of ~ means "no versions".

nav sets the left-bar navigation menu. The content of the linked file is an Asciidoctor unordered list.

Further reading

It’s probably worth looking at these pages in the Antora and Asciidoctor documentation:

Special pages

Home page

The English home page, https://techdocs.gbif.org/en/, is a component called ROOT, which is a special name where ROOT doesn’t show in links or URLs. Reserve pages in this section for the home page and very general pages about the whole manual.

Exactly what belongs in the home module isn’t very clear. It will be easier to work out once we have more documentation written. Perhaps a small amount of key information that we’d expect to be fully translated into supported languages?

OpenAPI

Auto-generated pages from OpenAPI endpoints are generated for our webservices.

The script fetch-openapi.py retrieves the OpenAPI definitions, and makes some rearrangements — some sections of the Registry are better documented as part of the Occurrences module. It also defines what is included in the "Key methods" version of the Registry, edit the script to add/remove methods.

There are three versions of the openapi Antora module, stored in en/openapi, en/openapi-v1 and en/openapi-v2. This structure is only visible to the user in the resulting URLs, and in Antora’s version menu which allows access to the old Maps V1 documentation. This structure will be more useful during and after our transition to V2 for the other modules.

It does mean links to the OpenAPI documentation need the version to be specified. See nav.adoc for the current links.

Site theme

The overall design of the site is controlled by a theme, tech-docs-theme. That sets the colours, fonts etc and adds the "Search docs" functionality.

Changing the site menus (on the green bar) is done by overriding the theme. Start at supplemental_ui/partials/header-content.hbs and copy + paste until you have what you want :-) (but remember pushing changes rebuilds the live site).

Additional Asciidoc syntax

In general editors should refer to the Asciidoctor documentation and the Antora documentation. Special syntax is used for:

OpenAPI pages

These are shown using Swagger, and a special page layout present in the site theme (see swagger.hbs for the source).

The OpenAPI source is retrieved whenever webservices are deployed, so it is always up-to-date. This is done on all environments; techdocs.gbif.org documents api.gbif.org and techdocs.gbif-uat.org documents api.gbif-uat.org.

Darwin Core Archive term tables

These are generated when the site is built using this Python script. The script generates a partial, which is included in the main pages.

UAT-only pages

Pages or parts of pages can be excluded from techdocs.gbif.org while they are under development. This also excludes them from search results.

Hiding a whole page from techdocs.gbif.org
ifeval::["{env}" == "prod"]
:page-unpublish:
endif::[]
Hiding part of a page
ifeval::["{env}" != "prod"]
On the UAT system …
endif::[]
Hiding an entry from the navigation (nav.adoc)
ifeval::["{env}" != "prod"]
* xref:page-name.adoc[]
endif::[]

Building

The site builds in Jenkins every time it is modified, see the status and badge above. To build it locally, the simplest method is to use Docker. See the Docker documentation for installation on Linux, Mac and Windows.

For routine use when authoring documentation, build just the English documentation and omit the search functionality. This uses a special cut-down playbook without some of the configuration suitable for a webserver:

./build-local-documentation.sh

To build English and Spanish and with the search function, and suitable for a webserver, run:

docker run --rm -t --user $(id -u) --volume $PWD:/antora:Z --env HOME=/antora antora/antora:3.0.1 npm i @antora/lunr-extension
for lang in en es; do
    docker run --rm -t --user $(id -u) --volume $PWD:/antora:Z antora/antora:3.0.1 tech-docs-$lang-playbook.yml
done

There is also internal documentation defined in internal.yml. This is built before the public documentation, which overwrites the CSS/JS output but leaves the internal documentation folders in-place. Therefore, the internal documentation doesn’t appear in the public component selector.

Please explore the Antora documentation for alternative methods for building, but they are all going to be more effort than installing Docker.