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

MPL-2.0