This is the the GBIF technical documentation site, visible at https://techdocs.gbif.org/.
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/. |
The document system uses Antora, a framework for combining documentation written in Asciidoctor from multiple Git repositories into a single documentation website.
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
ROOTmodule.
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.
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.adocThe 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.
It’s probably worth looking at these pages in the Antora and Asciidoctor documentation:
-
Family directories, to see where files for individual pages, images, attachments (downloads) etc. should be stored
-
Xref macros and page links and create page links to see how to make links within a page, between pages in the same module, different modules, different versions and different components.
-
The Antora documentation and the Asciidoctor documentation.
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?
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.
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).
In general editors should refer to the Asciidoctor documentation and the Antora documentation. Special syntax is used for:
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.
These are generated when the site is built using this Python script. The script generates a partial, which is included in the main 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.
ifeval::["{env}" == "prod"]
:page-unpublish:
endif::[]ifeval::["{env}" != "prod"]
On the UAT system …
endif::[]ifeval::["{env}" != "prod"]
* xref:page-name.adoc[]
endif::[]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.shTo 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
doneThere 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.