Skip to content

Latest commit

 

History

History
62 lines (47 loc) · 3.41 KB

README.adoc

File metadata and controls

62 lines (47 loc) · 3.41 KB

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://www.suse.com/documentation/ 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.

Fork the master branch for requesting changes to the SUSE CaaS Platform 4.0 and higher documentation.

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

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

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 it’s 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

  • 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