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 guidlines.

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 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

Your local checkout of the sources are going to be mounted into the container in order to built the docs. Depending on your UID on the host, you might see file permissions problems when trying to run make gen_docs. This is caused by the fact, that the docs user used within the container has a UID of 1000 by default. This might conflict with the user id of the mounted docs sources.

Your output might look like:

$ make gen_docs
mkdir -p build
rake aborted!
Errno::EACCES: Permission denied @ dir_s_mkdir - build

In this case you need to build the container with a different user ID. This will ensure that the docs user in the container will be able to create files and directories.

$ make build_docs_container IMAGE_UID=$(id -u)

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 the tooling 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 commands 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.