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.

You can check out the raw file of this topic or other existing Minishift topics to see examples of how the information is structured and which tags to use.

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

The image to build the documentation is downloaded from minishift/minishift-docs-builder. In case you need to make changes to the Dockerfile and want to build a local version of the image run:

$ make build_docs_container

If changes to the Dockerfile become part of a pull request, make sure to deploy a new version of the image to minishift/minishift-docs-builder. First increment the version of the image in the DOCS_BUILDER_IMAGE variable of the Makefile. Then run:

$ 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://<IP-of-Docker-daemon>: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.openshift.org

The Minishift documentation is deployed on docs.openshift.org under https://docs.openshift.org/latest/minishift.

To integrate with docs.openshift.org, we deliver a tarball that contains the Minishift AsciiDoc files as well as some AsciiBinder metadata files. This tarball is generated with a Jenkins job on CentOS CI and is triggered as part of a release.

Manually Building the OpenShift Documentation

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

Before you start, you need to check out the openshift-docs GitHub repository. You need all of the tooling required to build openshift-docs. See the Install and set up the tools and software section, which is part of the openshift-docs repository.

Make sure that the rake build command succeeds before integrating the Minishift documentation.

  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.