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.
The OpenShift Service mesh documentation is written in Asciidoc. This structure of this repository has been designed to work with both the upstream and downstream toolsets. To generate the documentation, you should install the following tools:
- Asciidoctor. The downstream (product) documentation toolset requires asciidoc, and while the main content format for Hugo is markdown, Hugo also supports asciidoc files by calling 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.
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 automatically generated from 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. ├── [public] - Generated output. (NOTE: This directory doesn't exist until you generate output.) ├── [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)
Creating New Content
The documentation is written in asciidoc. You can create new files from the command line, or by creating .adoc files in your favorite text editor.
To create a new file from the command line:
$ hugo new <section-name>/<new-content-lowercase>.adoc.
$ hugo new product-overview.adoc
$ hugo new ./overviews/about.adoc
You can also create new .adoc files using a text editor.
Content in the docs directory requires specific headers in orer to be listed. An example of this can be seen below.
--- 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.
To Build the Upstream Docs Web Site
The upstream docs use Hugo to generate the files for the web site.
Starting the Hugo Server
Hugo provides its own webserver 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:
$ hugo server
To start the Hugo server with draft files enabled run the following command:
$ hugo server -D
To start the Hugo server with live reload enabled, so that you can view changes immediately in your browser, run the following command:
$ hugo server --watch
To shut down the local server, use
CTRL + C.
When your site is ready to ship, you can shut down your preview server and issue a command to build the actual pages of the site. In Hugo, that would be just
hugo. Hugo puts the completed site in the
To generate the site output files:
To view the generated Hugo files, nagivate to the following directory:
For more information about Hugo commands, see the Hugo Web site.
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] (https://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).