$ make gen_docs
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.
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.|
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.
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.
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
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
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
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.
To view the Minishift documentation integrated into the OpenShift documentation, you can follow the following steps.
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.
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.