Documentation development

• The site has two parts: the versioned one is tied to a specific version (documentation), while the unversioned one includes the main pages of the site and shared assets.
• The versioned documentation is located in the /docs/documentation/ directory (the doc pages themselves are in /docs/documentation/pages/) and the module's docs directory (/(ee|ee/fe)?/modules//docs/).
• The unversioned documentation is located in the /docs/site/ directory (the pages themselves are in the /docs/site/pages/ directory).
• The documentation inside the module is stored in the docs directory as markdown files. An example: /modules/050-some-module/docs/README.md. The names of files in the docs directory of a module can only be the following:

  • README.md — A description of the module.

  • CONFIGURATION.md — page with the module setting. The page content is generated automatically from the OpenAPI schema in the openapi/config-values.yaml file of the module. Typical content:

    ---
    title: "Module name: configuration"
    ---
    
    <!-- SCHEMA -->
    

    Use one of the following placeholders:

    • <!-- SCHEMA --> — standard placeholder. Add a block with the information about bundles the modules includes in, information about How to explicitly enable the module…, and the module parameters.
    • {% include module-bundle.liquid %} — Adds a block with the information about bundles the modules includes in, and an information about How to explicitly enable the module….
    • {% include module-settings.liquid %} — Adds a block with the parameters

  • CR.md

  • EXAMPLES.md

  • FAQ.md

  • USAGE.md

  • ADVANCED_USAGE.md

• Insert the YAML front-matter block. Otherwise, the file will not appear on the site.
• Put the <!-- SCHEMA --> placeholder in the appropriate place on the page in the CR.md (and CR_RU.md) file so that CRDs in the module's crds directory can be generated on the site.
• Put the <!-- SCHEMA --> placeholder in the appropriate place on the page in the docs/CONFIGURATION.md and docs/CONFIGURATION_RU.md files to post the OpenAPI specification data on the module configuration page.
• Note that all cross-references in the versioned documentation are relative.
  • Wrong: [link](/module/020-two/configuration.html)
  • Correct:
    • [link](../../module/010-some-module/configuration.html)
    • [link](../010-some-module/configuration.html)
    • [link]({{ "/module/020-some-module/configuration.html" | true_relative_url }}) (the filter will make a relative link from an absolute one when rendering the site) - a universal, but cumbersome method.

Front-matter block

The YAML front-matter block in the header of the MD or HTML file can contain the following data:

• title - The title of the document.
• lang - language of the document. Default — en. Set it, if the document is not written in English.
• searchable — whether to add a document to the search results on the site. Can be false or true. Default — true.
• sitemap_include — whether to add a document to the sitemap. Can be false or true. Default — true.

OpenAPI specification

The x-doc- prefix in the parameter names is reserved in the OpenAPI specifications for rendering the documentation. Parameters with this prefix are only used for rendering the documentation and are not mandatory. A list of x-doc- parameters:

• x-doc-required: (boolean). It is used to indicate explicitly on the site if a particular parameter is mandatory or optional.
• x-doc-default: (arbitrary type). The default value to show on the site. It is helpful if you cannot specify the default parameter for some reason. The x-doc specification value must be of the same type as the target parameter, and it cannot contain markdown elements or arbitrary text (well, it can, but the rendering will be ugly). Only the value from the English version of the resource is used.
• x-doc-d8Revision (string). Sets a limit on the Deckhouse version the target parameter can be used with. Possible values: ce, ee (ce is the default value).
• x-doc-featureStatus (string). Sets the status of the feature and can be one of experimental or proprietaryOkmeter.
• x-doc-example (arbitrary type). Provides an example of the target parameter's value. If specified, it takes precedence over the example and x-examples parameters. The x-doc-example specification value can contain markdown elements or arbitrary text. Only the value from the English version of the resource is used.
• x-doc-search (string). Comma-separated search keywords. Are used in the search index on the site to search parameters better.

Images

Images used in the module documentation are stored in the /docs/documentation/images/<module-name>/ directory.

A link to an image file in the documentation is relative. An example: ![Image title](../../images/<module-name>/picture_name.png).

Running a site with the documentation locally

Read the instruction...