Commit c6a1b485 authored by Sarah White's avatar Sarah White

set up docs directory for Antora compliance

- set up component config and attributes files
- set up ROOT module
- set up playbook module
- sort monolithic playbook file into smaller files
- set up ROOT nav and index
- set up playbook nav and index
- move architecture files into architecture module
- rename arch content folder to documents
- modify _fragments path in module _attributes
- add environments header to files
parent 75e8418d
name: antora
title: Antora
version: 'master'
nav:
- modules/ROOT/nav.adoc
- modules/playbook/nav.adoc
:attachmentsdir: {moduledir}/assets/attachments
:fragmentsdir: {moduledir}/documents/_fragments
:imagesdir: {moduledir}/assets/images
:samplesdir: {moduledir}/samples
:moduledir: ..
include::{moduledir}/_attributes.adoc[]
When Antora runs, it performs the following steps:
. Clones (or pulls) the content repositories using git via NodeGit.
. Resolves and downloads the UI bundle using the GitHub API (unless it's already cached).
. Locates and reads all AsciiDoc files.
. Locates and reads all navigation files.
. Converts AsciiDoc files to embeddable HTML.
. Wraps the embeddable HTML in the page template and adds the navigation tree, which is also converted to HTML.
. Reads asset files (images, attachments, and UI resources).
. Writes all site files to [.path]_build/site_.
//The following sections describe a few of these steps in more detail.
= Content Fetching
ifndef::env-site,env-github[]
include::_attributes.adoc[]
endif::[]
:idprefix:
:idseparator: -
[abstract]
Antora's first step--probably the most important--is the fetching of the content.
This is the step that makes Antora so versatile.
Here's how it works.
The list of repositories is read from the playbook ([.path]_site.yml_).
Antora then uses git (via NodeGit) to clone or update these repositories.
The cloned repositories are stored under [.path]_build/sources_ (though this may be changed to [.path]_build/content_ in the future).
Each time Antora is run, the clone is synchronized with the remote repository.
Currently, the repositories are cloned bare, which means you won't actually see any files inside these directories aside from the [.path]_.git_ folder.
Antora then iterates over all the branches in these repositories and, using information from the playbook, decides which ones it will use.
It then scans those branches and puts the files into a vinyl collection, which is an in-memory collection of virtual file objects.
It associates each file in a branch with the component name and version defined in the [.path]_component.yml_ at the root of the branch.
As such, the repository name and branch name don't matter once the file is read.
The rest of Antora's pipeline interfaces only with this virtual file collection, not the git repositories, thus abstracting away the details of each file's origin.
// However, the virtual files do still retain some metadata about each file provided by the git repository.
= Antora Pipeline
ifndef::env-site,env-github[]
include::_attributes.adoc[]
endif::[]
:idprefix:
:idseparator: -
[abstract]
include::{fragmentsdir}/pipeline-steps-list.adoc[]
= UI Loading
ifndef::env-site,env-github[]
include::_attributes.adoc[]
endif::[]
:idprefix:
:idseparator: -
[abstract]
//As described in the {uri-ui-designer-guide}[UI Designer Guide], each UI bundle is stored as a zip that is attached to a release in the GitHub repository that hosts the UI project.
Each UI bundle is stored as a zip that is attached to a release in the GitLab or GitHub repository that hosts the UI project.
Antora resolves the latest release of the UI unless specified using the `tag` key.
It then downloads the UI bundle attached to that release.
Next, it extracts this zip file and adds the file contents to the vinyl collection previously described.
From that point forward, the pipeline interfaces only with the UI files in the virtual file collection, thus abstracting away the details of the UI's origin.
The UI bundle is cached inside [.path]_build_ after the first time you run Antora.
The cached bundle is used automatically on subsequent runs.
New UI releases *are not* picked up automatically.
If you want to force the generator to resolve and download a new UI bundle, you must pass the `--skip-theme-cache` switch:
$ node generate --skip-theme-cache
The alternative is to simply remove the build/themes directory, which is where the cache is stored.
If you fetch the UI often, you might find that you bump into the GitLab or GitHub rate limit.
If this happens, you can increase the limit by passing a https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/[personal access token] when you run the generator:
$ GITHUB_TOKEN=xxxxx node generate --skip-theme-cache
The UI provides both the design assets (e.g., CSS, fonts, shared images) as well as the template(s) for the pages.
Antora reads each AsciiDoc document, collects metadata from the document header, converts the document to embeddable HTML, then passes all the information to the template in the form of a page model.
The template then arranges the information and emits a standalone HTML page.
That page is put back into the virtual file collection in place of the AsciiDoc file, now ready to be written to disk as a page in the site.
//To learn more about designing a UI, visit the {uri-ui-designer-guide}[UI Designer Guide].
= Run Antora and Generate the Site
ifndef::env-site,env-github[]
include::_attributes.adoc[]
endif::[]
:idprefix:
:idseparator: -
:experimental:
:!table-caption:
[abstract]
Now that you've configured your playbook, it's time to run Antora.
//Now that you've told Antora which content to use and which UI to apply to that content, it's time to run it.
[#using-private-repositories]
.Using private repositories
IMPORTANT: If your playbook uses private repositories, you must have an SSH agent running with the identity (i.e., SSH key) you've linked to your GitHub account.
Otherwise, the generator will fail.
The SSH agent allows the generator to authenticate with private repositories on your behalf.
To learn how to generate an SSH key, start the SSH agent, add your identity, and add your SSH key to your GitHub account, please refer to the article https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent[Generating a new SSH key and adding it to the ssh-agent].
You invoke Antora by passing the `generate` command to Node (which runs the [.path]_generate.js_ script):
$ node generate
This script loads and executes Antora, passing along any trailing configuration flags and switches.
For example, you can specify a custom playbook as follows:
$ node generate --playbook=custom-site
Depending on your internet connection speed, it may take anywhere from a few seconds to several minutes to complete the generation process the first time you run it.
That's because it first has to download (i.e., `git clone`) all the repositories specified in the playbook.
When you run Antora again, the repositories are automatically updated (i.e., `git pull`).
These subsequent runs complete much faster because only the changes to the repositories have to be downloaded.
The repositories are cached under the [.path]_build_ directory.
If you remove the [.path]_build_ directory, the repositories will have to be downloaded again from scratch.
When generation is complete, you'll see a URL in the terminal that is specific to your machine.
[.output]
....
Loading theme bundle from GitHub release: ...
Using content from repository: ...
...
Finished in 0:00:45
Site can be viewed at file:///home/user/projects/docs-site/build/site
....
You can follow this URL to preview the site locally in your browser.
You do not need to publish the site to a server in order to preview it.
Depending on what you built, you may have to navigate to an HTML file from that location to see the actual site.
* xref:index.adoc[Pipeline Overview]
** xref:fetch-content.adoc[Fetching Content]
** xref:load-ui.adoc[Loading a UI]
* xref:run-antora-and-generate-site.adoc[Run Antora]
:attachmentsdir: {moduledir}/assets/attachments
:fragmentsdir: {moduledir}/documents/_fragments
:imagesdir: {moduledir}/assets/images
:samplesdir: {moduledir}/samples
:moduledir: ..
include::{moduledir}/_attributes.adoc[]
You configure Antora to generate the documentation site you want to make using a playbook.
The playbook provides Antora with the following information:
* [x] Which content repositories and branches to feed into the generator.
* [x] Which UI bundle to use to control the visual layout, style, and behavior of the pages in the site.
* [x] A list of paths of aspect navigation domains to use (navigation which is not linked to any given component).
* [x] The URL of the published site (used for canonical URLs and URLs in the sitemap).
* [x] The component which sits at the root of the site (i.e., the landing content).
= Author Mode
ifndef::env-site,env-github[]
include::_attributes.adoc[]
endif::[]
:idprefix:
:idseparator: -
:experimental:
[abstract]
Although the primary function of Antora is to generate a site for publishing, it also serves as a tool for the author.
By configuring the generator to use a local repository, author can preview their local content, including content which is not yet committed.
This section explains how this mode is activated and how it functions.
Author mode is activated when you configure the playbook to use a local clone for one or more of the content repositories.
The generator will use the repository where it lies instead of cloning it.
This scenario assumes you've already cloned a repository and want to incorporate it into the site generation.
To begin, create a folder named [.path]_workspace_ in the docs-site project.
$ mkdir workspace
Switch to the newly created directory and clone one of the repositories:
$ cd workspace &&
git clone https://github.com/my-antora-demo/server-docs
Next, open your playbook file and configure it to use this clone.
You can specify the repository either as a path relative to the root of the docs-site project or as an absolute path.
.site.yml (excerpt)
----
content:
- repository: workspace/server-docs
----
Now when you run the site generator, the contents of your local repository will be incorporated into the generator pipeline.
You may be wondering what branches the generator selects when the repository is local and whether it will pick up your uncommitted changes.
Here's how a local repository is handed:
* The repository is used in place instead of being cloned into build/sources.
* The repository is not updated; it's assumed the author will manage the repository
Here's how the branches are selected in the author mode scenario:
* Both local branches and remote branches associated with the remote named origin are considered
* If a local branch has the same name as a remote branch, the local branch is chosen
* The contents of the working tree get used in place of the files from the current branch.
Aside from its name, the current branch is effectively ignored.
If you want to use multiple working trees, simply clone the repository multiple times and configure multiple entries in the playbook.
You can use the `branches` key to filter out the names of branches you don't want.
= Configuring a Playbook
ifndef::env-site,env-github[]
include::_attributes.adoc[]
:icons: font
endif::[]
ifdef::env-github[]
:important-caption: :exclamation:
:note-caption: :paperclip:
:warning-caption: :warning:
endif::[]
:idprefix:
:idseparator: -
:experimental:
[abstract]
The default playbook is the file _site.yml_ at the root of the project.
It's written in YAML, a common configuration language for configuring automated tasks.
Antora automatically detects and uses this file if you don't specify an override.
The playbook makes it possible for writers to control what content is included in the site without needing any knowledge of programming knowledge.
It's particularly useful for creating a partial site for local preview.
Here's an example of a playbook:
.site.yml
[source,yaml,subs=attributes+]
----
site:
title: Docs Demo Site
content:
- repository: https://github.com/my-antora-demo/server-docs
branches: v*
- repository: https://github.com/my-antora-demo/aspnet-docs
branches: master
theme:
repository: https://github.com/my-antora-demo/docs-site-ui
----
The content key is likely the one you'll tune most often.
It contains an array of repository specifications.
At a minimum, you must specify the location of each public repository using the `repository` key.
Antora will then scan and use every branch in that repository that begins with "`v`" or is named "`master`".
If you only want to generate pages for a single component, you can trim the content key down to a single entry.
For example, here's how you'd configure the `content` key so that Antora only generates the server component (using the default branch set):
.site.yml (excerpt)
[source,yaml]
----
content:
- repository: https://github.com/my-antora-demo/server-docs
----
Instead of modifying the main playbook, you can create a custom playbook and pass it to the generator.
Start by creating a new file named [.path]_custom-site.yml_.
Populate it as follows:
.custom-site.yml
[source,yaml,subs=attributes+]
----
site:
title: Custom Docs Site
content:
- repository: https://github.com/my-antora-demo/server-docs
theme:
repository: {uri-ui-repo}
----
You then pass your custom playbook to the generator using the `--playbook` flag, as follows:
$ node generate --playbook=custom-site
TIP: You don't have to specify the file extension (i.e., `.yml`).
It gets added automatically if missing.
== Filtering Branches
If you want to limit the branches the generator scans and uses, you can specify an array of branch patterns using the branches key.
Each pattern is either an exact branch name or a shell glob pattern such as as `v3.*`.
If the pattern starts with a `!` character, then it is negated (i.e., the matches are excluded).
This is how you can deselect branches that were matched by the previous glob.
For example, let's say you want to include all 3.x versions of the server component except for 3.2.
You'd enter the following branches specification into the playbook:
.site.yml (excerpt)
[source,yaml]
----
- repository: https://github.com/my-antora-demo/server-docs
branches:
- v3.*
- '!v3.2'
----
IMPORTANT: A negated value must be enclosed in single quotes, per YAML rules.
Here's how you'd exclude all branches that end in `-beta`.
.site.yml (excerpt)
[source,yaml]
----
- repository: https://github.com/my-antora-demo/server-docs
branches:
- v*
- '!v*-beta'
----
== Altering the Metadata
The name of the repository and branch are ignored once the content is retrieved.
Metadata about the component is read from an configuration file in the repository instead.
Inside each branch you'll find a [.path]_component.yml_ file at the repository root.
That file defines the name and version of the component (i.e., the documentation version).
As an example, here's the [.path]_component.yml_ file in the v5.0 branch of the server repository:
.component.yml (excerpt)
[source,yaml]
----
name: server
version: '5.0'
----
This decoupling allows you to have more than one branch that provides the same version of a documentation component, which you can then toggle by configuring the branch filter in the playbook.
= The Playbook
ifndef::env-site,env-github[]
include::_attributes.adoc[]
:icons: font
endif::[]
ifdef::env-github[]
:important-caption: :exclamation:
:note-caption: :paperclip:
:warning-caption: :warning:
endif::[]
// Settings:
//:toc:
//:toc-title: Contents
:idprefix:
:idseparator: -
////
:ci-job-name: docs-prod-next
// URIs:
:uri-ui-repo: https://github.com/cb-docs-demo-201710/docs-site-ui
:uri-git: https://git-scm.com
:uri-git-dl: {uri-git}/downloads
:uri-node: https://nodejs.org
:uri-nodegit: http://www.nodegit.org
:uri-nodegit-dev: http://www.nodegit.org/guides/install/from-source
:uri-nvm: https://github.com/creationix/nvm
:uri-nvm-install: {uri-nvm}#installation
:uri-site-generator: https://gitlab.com/opendevise-projects/opendevise-site-generator-express
:uri-yarn: https://yarnpkg.com
:uri-ui-designer-guide: {uri-ui-repo}/blob/master/README.adoc
////
[abstract]
include::{fragmentsdir}/playbook-summary.adoc[]
////
There's one playbook preconfigured in this project.
Let's explore its contents.
Following that, you'll learn how to make your own playbook.
////
////
The UI is configured by pointing to the repository that hosts the UI project.
Details about how the UI is created, bundled, published, and consumed can be found <<UI Loading>>.
If you're interested in what happens behind the pipeline's scenes, head to <<The Generator Pipeline>>.
If you want to learn about creating and editing pipeline-compliant documents, see the xref:tech-writers-guide.adoc#[tech writer's guide].
== Next Steps
You now understand how to configure the site generator using a playbook and work with local content.
You can now move on to the xref:tech-writers-guide.adoc#[tech writer's guide] to learn how to work with the content in the site, including how to make references between pages, or read the xref:aspect-navigation.adoc#[aspect navigation guide] to learn how to create task flows that span documentation components.
////
* xref:index.adoc[Playbook]
** xref:configure-playbook.adoc[Configure Playbook]
** xref:author-mode.adoc[Configure Author Playbook]
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment