Skip to content

Latest commit

 

History

History
86 lines (63 loc) · 4.94 KB

readme.adoc

File metadata and controls

86 lines (63 loc) · 4.94 KB
Raw

Apicurio Registry user documentation

The Apicurio Registry user documentation is created using AsciiDoc (https://asciidoc.org/). This readme describes the user documentation conventions and directory structure, and explains how to build the documentation using the Antora site generator (https://antora.org/).

How the documentation is orgainized

The Apicurio Registry user documentation is organized for delivering flexible content, which is a framework for putting together exactly the content you need, and making it easier to reuse the same content in multiple places. This framework includes the following building blocks:

  • Assemblies are files that introduce a subject and include modules, which provide the content.

  • Modules provide content and do not include other files. There are three kinds of modules:

    • Concept - Overview and definitions

    • Procedure - Steps on how to perform a specific task

    • Reference - Supplementary information for more details

Explanation of the directory structure

The apicurio-registry/docs directory structure includes the following:

Component Description

getting-started

AsciiDoc directory for the Getting Started guide. Includes the master.adoc file which defines what content assembly files are included, and symlinks to the modules directory. This is not required for building with Antora.

modules

Includes all the assemblies and content modules required for Antora:

  • Assemblies: modules/ROOT/pages

  • Modules (concept, procedure, and reference): modules/ROOT/partials

  • Images: modules/ROOT/assets/images

  • Downloads: modules/ROOT/assets/attachments

  • Navigation: modules/ROOT/nav.adoc

rest-api

Build Apicurio Registry REST API documentation from source code.

antora.yaml

Component descriptor file for Antora.

local-test-playbook.yml

Antora playbook for test builds. Controls what content is included, what user interface is applied, and where the site is published.

For more details, see:

REST API documentation

The Apicurio REST API documentation is generated dynamically from the Apicurio Registry OpenAPI v3.0 Swagger file using ReDoc.

You can generate the latest Apicurio Registry REST API documentation when building from the source code by following the instructions in rest-api/readme.adoc.

The Apicurio REST API documentation is also published in the user documentation content using the following file: docs/modules/ROOT/assets/attachments/registry-rest-api.html

Tips for contributing AsciiDoc content

  • Fork the Apicurio Registry project to edit the documentation source files. You can then submit your changes in a pull request as you would any other contribution to the project.

  • Create a concept module to introduce a new feature, for example: modules/ROOT/partials/getting-started/con-my-new-feature.adoc

  • Create a procedure module to describe the steps on how to use your new feature, for example: modules/ROOT/partials/getting-started/proc-configuring-my-new-feature.adoc

  • Create a reference module to describe any optional configuration for your new feature, for example: modules/ROOT/partials/getting-started/ref-my-new-feature-environment-variables.adoc

  • Create an assembly to group all the information about your new feature, for example: modules/ROOT/pages/getting-started/assembly-using-my-new-feature.adoc

  • Add an entry for your assembly file to modules/ROOT/nav.adoc to display a link for your assembly in the documentation navigation.

For examples of how to structure your content, see the existing content in the modules/ROOT directory.

Tips for formatting and styling content

For more details and examples of how to create technical content using AsciiDoc source files, see Tips for creating AsciiDoc content

Building the documentation using Antora

You can perform a local build of the documentation for test purposes using the antora tool (https://antora.org/):

  1. Install the antora tool using the following steps: https://docs.antora.org/antora/2.3/install-and-run-quickstart/

  2. In the apicurio-registry/docs directory, enter the following command:

    $ antora local-test-playbook.yml

  3. Change to the apicurio-registry/docs/target/dist directory.

  4. Open the generated index.html file in your browser.

For details on how the Apicurio Registry project documentation website is automatically generated, see https://github.com/Apicurio/apicurio-docs-playbook.