include::variables.adoc[]

= Writing and Publishing {project} Documentation
:icons:
:toc: macro
:toc-title:
:toclevels: 2

toc::[]

[[writing-docs-overview]]
== Overview

{project} documentation is located in the *_docs_* sub-directory of the {project} repository.
The documentation is a mix of auto-generated https://en.wikipedia.org/wiki/Markdown[Markdown] files and manually maintained https://en.wikipedia.org/wiki/AsciiDoc[AsciiDoc] files.

[[contribute-to-docs]]
== Contributing to the Documentation

{project} is an open-source project and we welcome contributions.
Similar to code contributions, if you want to add or edit {project} documentation, you can create an issue in our link:https://github.com/minishift/minishift/issues[Github issue tracker] and submit a pull request with the changes.

[[docs-conventions-guidelines]]
== Conventions and Guidelines

{project} documentation is authored in the link:http://asciidoctor.org/docs/asciidoc-syntax-quick-reference[AsciiDoc] markup format.
Since {project} is closely related to the OpenShift Origin project, we follow the link:https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc[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 {project}, or Command Reference.

[TIP]
====
You can check out the link:https://raw.githubusercontent.com/minishift/minishift/master/docs/source/contributing/writing-docs.adoc[raw file] of this topic or other existing {project} topics to see examples of how the information is structured and which tags to use.
====

[[common-conventions]]
=== Commonly-Used Conventions

- Each file must contain a topic metadata header with a top-level heading followed by required AsciiDoc variable declarations.
See the link:https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc#topic-metadata[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 link:https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc#internal-cross-references[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 link:https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc#unique-ids[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-new-topic]]
=== 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-docs-locally]]
== 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 {project} itself.
For more information, see xref:../using/docker-daemon.adoc#[reusing the Docker daemon].

To generate the documentation into the *_docs/build_* directory, run:

----
$ make gen_docs
----

[NOTE]
====
The image to build the documentation is downloaded from link:https://hub.docker.com/r/minishift/minishift-docs-builder/:[minishift/minishift-docs-builder].
In case you need to make changes to the link:https://github.com/minishift/minishift/blob/master/docs/Dockerfile[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 link:https://hub.docker.com/r/minishift/minishift-docs-builder/:[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-okd-io]]
== Integration with docs.okd.io

The {project} documentation is deployed on *docs.okd.io* under link:https://docs.okd.io/latest/minishift[https://docs.okd.io/latest/minishift].

To integrate with *docs.okd.io*, we deliver a compressed archive that contains the {project} AsciiDoc files as well as some link:http://www.asciibinder.org/[AsciiBinder] metadata files.
This archive is generated by a link:https://ci.centos.org/job/minishift-release[release job] which is triggered by an xref:../contributing/releasing.adoc#automated-release[automated release].
The generated archive is located on the link:http://artifacts.ci.centos.org/minishift/minishift/docs/latest/[artifact server].

[[manually-building-openshift-docs]]
=== Manually Building the OpenShift Documentation

To view the {project} documentation integrated into the OpenShift documentation, you can follow the following steps.

[NOTE]
====
Before you start, you need to check out the link:https://github.com/openshift/openshift-docs.git[*openshift-docs*] GitHub repository.
You need all of the tooling required to build *openshift-docs*.
See the link:https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/tools_and_setup.adoc[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 {project} documentation.
====

. In the local {project} repository, build the {project} 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 {project} 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_*.

[[building-openshift-docs-using-centosci]]
=== Building the OpenShift Documentation using CentOS CI

To view {project} 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`     : {project} CentOS CI API key
  - `user-repo`   : User repository URL. Defaults to {project} repo URL
  - `docs-branch` : Branch containing documentation changes. Defaults to `master` branch

This will trigger the link:https://ci.centos.org/job/minishift-docs/[minishift-docs] job.
After the job is completed successfully, the location of the hosted {project} documentation can be found at the end of the build logs.
