$ 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 guidelines.
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 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 $ 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
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 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.
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 |
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.
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.