Skip to content

Latest commit

 

History

History
161 lines (113 loc) · 8.86 KB

antora-site-structure.md

File metadata and controls

161 lines (113 loc) · 8.86 KB
Raw

Antora Site Structure for Docs

Table of Contents

  1. Why Antora
  2. Scope of Documentation Repositories
  3. Scope of Content Accessibility
  4. Structure of Directories
  5. Scope of Antora Definitions
  6. The Antora UI Template

Why Antora

The main reasons for using Antora are the following:

  1. It uses and extends the asciidoc text writing format.

  2. It extends asciidoc with multi-repo capabilities.

  3. The writer does not need to care about repos, or content locations, etc. anymore as this is virtualized by Antora and content can be accessed in a standardized way via Resource ID Coordinates.

  4. Antora distincts writing the documentation and the UI-Template defining how the content is presented.

Scope of Documentation Repositories

The ownCloud documentation consists of a building repo named docs which has NO content and additional repos like ocis or the clients which are included as content sources defined in site.yml.

Our setup is made in a way, where each repo can build it's own content individually for local testing and checking validity. Only the build of the docs repo creates documentation which is pushed to the web. There is one exception, when reenabled, PDF's are created AND pushed via the CI from the content source where it applies.

Note that the docs-main repo only contains the entry page but no detailed product description.

repo        content source

docs   -->  docs-main
            docs-ocis
            docs-client-desktop
            docs-client-ios-app 
            docs-client-android
            ...

Note that the arrow from repo to content source is intentionally unidirectional in our setup and should be respected. See more details about the reason below.

Scope of the playbook files (site.yml)

In general, only one site.yml file is neccessary for the whole environment and its definitions are available to the whole site. This site.yml file is located in the docs repo. We have additionally for each content source its own site.yml for testing purposes only. The scope of these local site.yml files is restricted to the respective content source and any definitions made are not availabe outside.

Due to this fact, you need to re-add all relevant attributes to the site.yml file as defined in the sourced site.yml file which accesses it, else a local build will return warnings about unresolved attributes. This is also valid for the building repo.

Note that this behaviour is relevant for the playbook site.yml files only and does not apply to the component descriptor files antora.yml.

Scope of Content Accessibility

Because Antora is capable of defining additional content sources, you can access content from these resources. The setup is flat, no main/child environment. To access resources, follow the Resource ID Coordinates scheme.

Because of the setup we have made regarding testing, the direction of the arrow is important.

Possible

docs    --> docs-client-ios-app
            └> index.adoc

Main (docs) can access content from any content source (like docs-client-ios-app) and vice versa at build time , because docs has referenced the repo (content source) and made it available to all.

Impossible

docs-client-ios-app    --> docs-client-desktop
                           └> index.adoc

docs-client-ios-app    --> docs
                           └> index.adoc

When doing a build of a content source (like the docs-client-ios-app) which is neccesary for testing purposes, any references to another content source or to docs will fail as the referenced content source is unknown. Those references will throw an error/warning. Even if it is not the best approach, use .html references to any other source outside the working repo.

Structure of Directories

All doc repositories have an identical directory structure. This helps maintaining and accessing content easily.

The Antora Directory Structure

modules/named-module-1/attachment
                      /examples
                      /images
                      /pages
                      /partials

       /named-module-2/attachments
                      /...
       /...

Please see Standard File and Directory Set at Example 1 for details.

Note that there is one important exception: The navigation file nav.adoc is under the partials directory and not at the level of the named-module (like ROOT or admin ect). This is necessary because only files which are in a family directory can be accessed from outside. This means docs can access e.g. nav.adoc at any content source like docs-client-ios-app.

Other Necessary Directories

Beside the necessary directories for node, other important directories are:

bin/              Helper scripts to maintain the documentation
book_templates/   Template file(s) to create the pdf file
ext-antora/       Antora extensions necessary for the build process
ext-asciidoc/     Asciidoc extensions necessary for the build process
pdf_web/          Output directory of generated pdf files, only used locally!
public/           Output directory of generated html files, only used locally!
resources/        Themes necessary for creating pdf files
tmp/              Temp directory used for htmltest (broken link checking)

Important files

The following files are important to run a build properly; note that node related stuff is not mentioned explicitly:

.drone.star       Define the build process steps when triggered by a PR
                  necessary for the creation of the pdf file 
package.json      Define the antora environment und scripts to run at the cli
antora.yml        Contains source files and attributes that only belong
                  to the component (version dependent!)
site.yml          Global site definitions including attributes (version independent!)

Scope of Antora Definitions

Versioning

While you can read more details about What is antora.yml? and What is site.yml (the playbook), here are some important items:

To manage versions in docs, we use branches. This means that any content based on a variable (attribute) limited to a branch must go into the component description file antora.yml and be maintained accordingly. Any attribute that can be used in any branch of a component must be defined in site.yml

Accessibility and Availability of Attributes

  1. The scope of attributes defined in a page is limited to that page only.
  2. The scope of attributes defined in antora.yml is limited to the branch and component where it is defined. This is also true for attributes that should be accessed from the UI-Template.
  3. The scope of attributes defined in site.yml is global. The term global has two flavours in our setup:
    1. When used in the building repo docs, it becomes available to all sources at any time.
    2. When used in a content source, it is only availabe to the content source during a local test build.
  4. Attributes starting with page- are also available to the UI-Template when running a build. The rules above apply. This is important when defining UI content based on attributes. To access these attributes in the UI-Template use page.attribute.name where name is without leading page- For details see AsciiDoc Attributes in Antora.

IMPORTANT
If used attributes are not defined during build time, Antora hard stops and files an error. You must fix those issues BEFORE creating the PR - else it never will get green. Also see the CI log for details.

The Antora UI Template

As described on top, Antora separates the writing of text and the presentation design. Our presentation design is defined in the docs-ui repository. Any change made in the UI affects the complete documentation, careful tests are mandatory.