Writing and Publishing Minishift Documentation

Overview

Minishift documentation is located in the docs sub-directory of the Minishift repository. The documentation is a mix of auto-generated Markdown files and manually maintained AsciiDoc files.

Contributing to the Documentation

Minishift is an open-source project and we welcome contributions. Similar to code contributions, if you want to add or edit Minishift documentation, you can create an issue in our Github issue tracker and submit a pull request with the changes.

Conventions and Guidelines

Minishift documentation is authored in the AsciiDoc markup format. Since Minishift is closely related to the OpenShift Origin project, we follow the OpenShift Documentation Guidelines for tagging, formatting, and structure wherever possible.

The documentation source structure follows a modular format, where each file is called a topic and each topic is stored under a sub-folder based on the relevant category, such as Getting Started, Using Minishift, or Command Reference.

Commonly-Used Conventions

• Each file must contain a topic metadata header with a top-level heading followed by required AsciiDoc variable declarations. See the topic metadata section in the OpenShift documentation guidelines for more information.

• Links to another location within an AsciiDoc topic or between AsciiDoc topics are called cross-references and should use the xref notation. See the internal cross-references section of the OpenShift documentation guidelines for more information and examples.

• Each section heading must be preceded by a unique anchor ID, to help make sure that cross-references resolve to the correct section. The anchor ID text should match the title as much as possible. See the unique IDs section of the OpenShift documentation guidelines for more information and examples.

• To make documentation reviews easier on GitHub, we use one line per sentence wherever possible. This practice is in addition to the OpenShift documentation guidelines.

Adding a New Topic

If you are adding a new topic to the documentation library, you must also update the navigation in the following ways:

• Add an entry to the relevant index.adoc file for that topic. For example, if you add a new topic in the docs/source/using/ directory, you must update the docs/source/using/index.adoc file in the same directory.

• Add an entry to the _topic_map.yml in the docs/source sub-folder. The entry must contain the topic title and the file name.

Make sure to add the new topic in the same order in all of the locations.

Building the Documentation Locally

By default, the documentation is built in a Docker container. This way you do not need to install all of the required dependencies on your development machine. All you need is a running Docker daemon. In case you don’t have one, use Minishift itself. For more information, see reusing the Docker daemon.

To generate the documentation into the docs/build directory, run:

$ make gen_docs

$ make build_docs_container

$ make push_docs_container

To build and serve the documentation for editing, run:

$ make serve_docs

The make serve_docs command builds and generates a live-preview of the documentation. You can access the documentation by browsing to http://:4567.

To verify all links (external as well as internal ones), run:

$ make link_check_docs

If you encounter issues with the local staging of the documentation, you can run the following command to remove all build artifacts:

$ make clean_docs

Integration with docs.okd.io

The Minishift documentation is deployed on docs.okd.io under https://docs.okd.io/latest/minishift.

To integrate with docs.okd.io, we deliver a compressed archive that contains the Minishift AsciiDoc files as well as some AsciiBinder metadata files. This archive is generated by a release job which is triggered by an automated release. The generated archive is located on the artifact server.

Manually Building the OpenShift Documentation

To view the Minishift documentation integrated into the OpenShift documentation, you can follow the following steps.

1. In the local Minishift repository, build the Minishift documentation tarball.

$ make gen_adoc_tar

After the build completes there will be a minishift-adoc.tar file in the docs/build directory of the local Minishift repository.

1. In the local openshift-docs repository, run the following commands:

$ mkdir minishift
$ cd minishift
$ cp <path to tarball> .
$ tar -xvf minishift-adoc.tar --strip 1
$ cat _topic_map.yml >> ../_topic_map.yml
$ cd ..
$ rake build

If the build completes successfully, the site is available under preview/openshift-origin/latest/welcome/index.html.

Building the OpenShift Documentation using CentOS CI

To view Minishift documentation integrated into the OpenShift documentation using CentOS CI, trigger the documentation build using following:

$ export API_KEY=<api-key>
$ export REPO=<user-repo>
$ export BRANCH=<docs-branch>
$ curl -H "$(curl --user minishift:$API_KEY 'https://ci.centos.org//crumbIssuer/api/xml?xpath=concat(//crumbRequestField,":",//crumb)')" -X POST https://ci.centos.org/job/minishift-docs/build --user "minishift:$API_KEY" --data-urlencode json='{"parameter": [{"name":"REPO", "value":"'$REPO'"}, {"name":"BRANCH", "value":"'$BRANCH'"}]}'

where

• api-key : Minishift CentOS CI API key

• user-repo : User repository URL. Defaults to Minishift repo URL

• docs-branch : Branch containing documentation changes. Defaults to master branch

This will trigger the minishift-docs job. After the job is completed successfully, the location of the hosted Minishift documentation can be found at the end of the build logs.