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://: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 . $ 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= $ export REPO= $ export 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.