= 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 organized

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

//For more details, see the https://redhat-documentation.github.io/modular-docs/[Modular Documentation Reference Guide]

=== Explanation of the directory structure

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

[options="header"]
[cols="1,2"]
|===
|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`
a|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: 

* link:https://docs.antora.org/antora/2.0/component-structure/[Organizing Your Documentation for Antora]
* link:https://docs.antora.org/antora/2.0/playbook/[The Antora Playbook]
* link:https://docs.antora.org/antora/2.0/navigation/filenames-and-locations/[Antora Navigation Files and Storage Locations]

=== REST API documentation
The Apicurio REST API documentation is generated dynamically from the Apicurio Registry OpenAPI v3.0 Swagger file using link:https://github.com/Redocly/redoc[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 link:tips-for-creating-asciidoc-content.adoc[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/):

. Install the `antora` tool using the following steps: https://docs.antora.org/antora/2.3/install-and-run-quickstart/
. In the `apicurio-registry/docs` directory, enter the following command:
+
----
$ antora local-test-playbook.yml
----
+
. Change to the `apicurio-registry/docs/target/dist` directory.
. 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.  
