https://github.com/opendevstack/ods-documentation
Antora playbooks to generate the versioned documentation
https://github.com/opendevstack/ods-documentation
Last synced: 2 months ago
JSON representation
Antora playbooks to generate the versioned documentation
- Host: GitHub
- URL: https://github.com/opendevstack/ods-documentation
- Owner: opendevstack
- Created: 2019-05-22T10:12:35.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2025-04-10T02:40:51.000Z (2 months ago)
- Last Synced: 2025-04-10T03:34:05.017Z (2 months ago)
- Language: CSS
- Homepage:
- Size: 93.5 MB
- Stars: 0
- Watchers: 31
- Forks: 6
- Open Issues: 11
-
Metadata Files:
- Readme: README.adoc
- Changelog: CHANGELOG.adoc
Awesome Lists containing this project
README
# The ODS Antora Playbook Repository
## Building documentation locally
### Prerequisites
- Antora (3.1) has to be installed according to the https://docs.antora.org/antora/3.1/install/install-antora/[Install Antora] guide.
- The following OpenDevStack repositories have to be cloned and stored beside the `ods-documentation` repository: `ods-core`, `ods-jenkins-shared-library`, `ods-provisioning-app` and `ods-quickstarters`.
### Generate docs using `site-workspace.yml`
To preview your local changes, just building documentation from `HEAD`.
antora generate site-workspace.yml
The output will be written to `docs_local`, which is ignored by git. This directory is only for local preview and verification.
### Generate docs using `site-workspace-full.yml`
To preview your local changes, taking into account all branches.
antora generate site-workspace-full.yml
The output will be written to `docs_local`, which is ignored by git. This directory is only for local preview and verification.
Note that for this playbook, you will also need the following repositories locally:
- `opendevstack.github.io`
- `ods-project-quickstarters`
### Customize the UI
By default, the playbooks reference a UI bundle from https://github.com/opendevstack/ods-docs-ui/releases. You can also clone that repo locally, customize the UI, build a new UI bundle and reference that when running `antora`.
To build a UI bundle, read the documentation at
https://github.com/opendevstack/ods-docs-ui/blob/ods-docs-ui/README.adoc. Example:
cd ../ods-docs-ui
# Compile
npm install
# Create file ui-bundle.zip
gulp bundle
# Reference it
cd ../ods-documentation
antora generate site-workspace.yml --ui-bundle-url ../ods-docs-ui/build/ui-bundle.zip
### Search Function
A search index is created by the antora lunr extension.
## Building using GitHub Actions
Whenever this repository is pushed to GitHub, it triggers a build using GitHub Actions,
that regenerates the antora documentation based on the `site.yml` playbook (which fetches the different referenced repositories from GitHub). The
updated content in directory `docs` will be pushed back to the GitHub repository during the build. The build environment uses the GitHub Token (env: GITHUB_TOKEN) with write privileges to the repository.
See xref:.github/workflows/renderDocs.yml[.github/workflows/renderDocs.yml] for details.