osc-doc-framework

osc-doc-framework is a framework used to generate OUTSCALE documentations. It is primarily based on the Antora documentation site generator, with extension and theme files to customize the Antora output.

Prerequisites

• You need to install node 16.0.0 or later from the official Node.js website or via the Node Version Manager (nvm).

• You need to create an Antora documentation project. For more information, see the official Antora documentation.

Installing

There are multiple ways to install osc-doc-framework in your Antora documentation project. Here is an example:

$ cd <YOUR_ANTORA_PROJECT>
$ git clone https://github.com/outscale/osc-doc-framework.git
$ npm install ./osc-doc-framework

Then, in your Antora playbook file, you can plug the different components of osc-doc-framework by adding the following keys:

ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
  supplemental_files: ./node_modules/@outscale/osc-doc-framework/antora-theme
antora:
  extensions:
    - require: ./node_modules/@antora/lunr-extension
    - require: ./node_modules/@outscale/osc-doc-framework/antora-search-page-extension
    - require: ./node_modules/antora-navigator-extension
    - require: ./node_modules/@outscale/osc-doc-framework/antora-extension
    - require: ./node_modules/@outscale/osc-doc-framework/antora-git-log-extension
    - require: ./node_modules/@outscale/osc-doc-framework/antora-rss-extension

Linting

Optionally, you can configure your Git to use the pre-commit hook in the git-hooks folder. This pre-commit hook will run Vale on your documentation pages in order to lint them with the style rules located in the Vale/styles folder.

Building

Once you have installed osc-doc-framework, you can build your documentation in the usual Antora way:

$ npx antora <YOUR_PLAYBOOK_YML>

Contributing

Feel free to open an issue in case of bugs.

License

Copyright Outscale SAS

MPL-2.0