/doc-caasp

SUSE Container as a Service Platform Documentation

Primary LanguageShellOtherNOASSERTION

SUSE CaaS Platform Documentation

Build Status

This is the source for the official SUSE CaaS Platform documentation

Released versions of the documentation will be published at https://documentation.suse.com/ once available.

Contributing

Important
Allow maintainer updates for pull requests
When creating a Pull Request please allow maintainers to push commits into your fork. See: https://help.github.com/en/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork

If you would like to contribute, please fork this repository and send pull requests.

For help on style and structure, refer to the Documentation Styleguide

Branches

Important
 Changes to already released versions of the documentation must be merged to a maintenance/CaaSX branch from the maintainer.

We maintain three versions of the product at this point:

  • master (ongoing 4.5.x work)

  • maintenance/CaaS4.5 (4.5.x released version and incremental updates)

  • maintenance/CaaS4 (4.2.x released version and incremental updates)

Files and Directory Structure

  • DC-caasp-*: Configuration files for the exported guides.

  • adoc/: Contains all the pages that make up the content.

  • adoc/book_*: Meta files collating pages into a guide document.

  • adoc/attributes.adoc - Contains all version numbers of the product and its components. Also contains the release_type flag that determines if the branch contains an public or (SUSE) internal release.

  • adoc/entities.adoc - Contains text substitutions for often used component names and strings.

  • adoc/common_*: Include files with common information like legal disclaimers and licenses.

  • adoc/admin-*: Pages belonging to the Admin guide.

  • adoc/deployment-*: Pages belonging to the Deployment guide.

  • adoc/architecture-*: Pages belonging to the Architecture guide.

  • adoc/quick-*: Pages belonging to the Quickstart guide.

Editing AsciiDoc

To contribute to the documentation you will use AsciiDoc syntax.

  • You can learn about AsciiDoc syntax at https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

    • A much more detailed manual can be found here

  • For simple preview use the browser extensions for

    • Chrome

    • Firefox

    • Make sure you set the "security" setting in the Extension Preferences to server

  • SUSE documents are generally built with DAPS (package daps) and the SUSE XSL Stylesheets (package suse-xsl-stylesheets). It’s available as a SUSE rpm package from the the SUSE repository Documentation:Tools or directly from Github.

  • If you are running a (recent) version of openSUSE, you can install our documentation toolchain with the following command: sudo /sbin/OneClickInstallUI https://gitlab.nue.suse.com/susedoc/doc-ymp/raw/master/Documentation.ymp

  • If you don’t want to download the entire documentation toolchain, you can also build documentation using DAPS inside a Docker container with daps2docker:

    • Clone the daps2docker repository.

    • Change directory to the folder which contains your documentation source files (doc-caasp).

    • Execute the daps2docker.sh file, for example by running ../daps2docker/daps2docker.sh ..

    • Follow the commandline instructions for further building options.

  • Basic daps usage:

    • $ daps -d DC-<YOUR_BOOK> validate: Make sure what you have written is well-formed XML and valid DocBook 5

    • $ daps -d DC-<YOUR_BOOK> pdf: Build a PDF document

    • $ daps -d DC-<YOUR_BOOK> html: Build multi-page HTML document

    • Learn more at https://opensuse.github.io/daps