Skip to content

Latest commit

 

History

History
93 lines (68 loc) · 4.78 KB

README.adoc

File metadata and controls

93 lines (68 loc) · 4.78 KB
Raw

OpenShift Service Mesh

This repository contains documentation for the community release of OpenShift Service Mesh, based on the upstream Istio project. This README provides information about this documentation repository. The site can be viewed at maistra.io.

Tooling

Maistra has a variety of tooling located in the tools directory.

  • checkLinks.sh CheckLinks is a wrapper around the html-proofer tool that runs on pull requests to make sure that links are valid.

  • runLinter.sh We use the Vale linter to validate our documentation. This script is a wrapper that runs on pull requests to verify documentation.

  • updateFields.sh Maistra ties together several different tools and exposes the ability to configure all of them through the ServiceMeshControlPlane. This script keeps everything in sync.

Getting Started

The Maistra documentation is written in [AsciiDoc](http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/). To generate the documentation, you should install the following tools:

  • Hugo

  • Asciidoctor

  • Text editor of your choice, for example the Atom text editor has several useful packages that make it easier to work with AsciiDoc and Hugo.

Repository Structure

Hugo assumes that the same structure that organizes your source content is used to organize the rendered site.

This repository uses the following directory structure:

├── [archetypes] - Can be used to define content, for example you can set default tags or categories and define types such as a post, tutorial or product here.
├── [topics] - Contains all the content files.
|   ├── Blog -- This directory is used to render the Maistra blog, which is rendered on the fly from a collection of RSS feeds.
|   ├── Docs -- This directory contains
│   │   ├── .adoc (AsciiDoc topic files)
│   ├── DRAFTS - This directory is intended for topic stubs, topics that need to be written, and in-progress drafts. The Hugo config file is set to ignore this directory and its contents.
│   │   ├── .adoc (AsciiDoc topic files)
├── [data] - Site data such a localization configurations go here.
├── [layouts] -  Layouts for the Go html/template library which Hugo utilizes.  Note that themes override layouts.
├── [static] - Any static files here will be compiled into the final website.
|   ├──  img - This directory contains all the images.  Hugo expects this directory name.
│   │  ├── .png
├── [themes] - This directory contains the theme for the site.
├── config.toml - Main Hugo configuration file, used to define the websites title, language, URLs etc.
├── README.md (This file)

Docs Header

Content in the docs directory require the following headers to be populated in order to be listed in the docs:

---
title: "Bookinfo"
type: "document"
category: "Examples"
description: "Bookinfo is an example application that shows you how to set up and monitor a service mesh using Istio."
---

For more information about writing modular documentation, see the [Modular Documentation Reference Guide](redhat-documentation.github.io/modular-docs/).

Previewing Changes Locally

Hugo provides its own web server which builds and serves the site. By default Hugo will also watch your files for any changes you make and automatically rebuild the site. It will then live reload any open browser pages and push the latest content to them.

To start the Hugo server run the following command: ` $ make serve `

Content can be verified using the linter and link checker: ` $ make check-links lint `

The full site output can be produced using the following command: ` $ make build `

Releases

Release content in Maistra.io is driven by a combination of two files in the data directory:

  • data/release.yaml selects the latest release of Maistra to generate content from

  • data/releases/release.yaml, where release.yaml is the Maistra version, contains common information about the release. It contains the following fields:

Submitting a Pull Request

You can close a GitHub issue from a Pull Request. All you have to do is include the [special keyword syntax] (help.github.com/articles/closing-issues-using-keywords/) (for example, “fixes #5) in the body of your Pull Request. When the pull request is merged into your repository’s default branch, the corresponding issue is automatically closed.

Commit messages against Jira should start with the project name associated with the PR. If the PR is to address MAISTRA-123 then the commit message for the PR must start with "MAISTRA-123 " and then followed by the detailed commit message (no semi-column or dash between the Jira ID and text, no brackets…​ just a space).