Contribute to Atomic Host Documentation

The post describes how you can contribute to Atomic Host Documentation. If you do not know what Atomic Host is, please refer to: http://www.projectatomic.io.

Atomic Host Documentation focuses on covering Docs required for Atomic Host Introduction, Installation, Cluster set up with Kuberenetes/Openshift etc to how to compose, manage and deploy Atomic Host and its various application.

Atomic Host Documentation will also support Fedora Atomic Documentation and CentOS Atomic Documentation within the same repository in near future as AsciiBinder has ability to build Docs with multiple distros and versions.

Requirements:

• AsciiDoc markup language to write Docs.
• Asciidoctor that acts as text processor to convert AsciiDoc content to HTML5, DocBook and others.
• AsciiBinder that helps to build, maintain documentation in easier way.

Set up Development Environment:

The following creates development environment and installs required libraries/packages on your local system which are required in order to write/build Doc for Atomic Host.

$ sudo dnf install ansible
$ git clone https://github.com/projectatomic/atomic-host-docs.git
$ cd atomic-host-docs/
$ git checkout -b branchname
$ ansible-playbook setup.yml --ask-sudo-pass

How to Write Doc:

Atomic Host Documentation uses AsciiDoc markup language. You can have a look at the Reference for AsciiDoc Syntax.

The following procedure demonstrates how you can write and build Doc.

$ mkdir container
$ touch container/overview.adoc

 

container/overview.adoc

[[container-overview]]
= Container Overview
{product-author}
{product-version}
:data-uri:
:icons:

Container contains applications in a way to keep itself isolated from the host system that it runs on and
container allows developer to package an application with all of it parts, such as libraries and other packages
it needs to run and ship it all as one package.
I love Containers!!!

 

After the Doc is ready, we need to make entry in topic_map.yml file. This file tells AsciiBinder which topic groups and topics to generate.

_topic_map.yml

---
Name: Tools
Dir: container
Topics:
  - Name: Overview
    File: overview

 

Now go to the root directory of the repo. The following command will build the Documentation.

$ asciibinder

Verify:

A new directory will be created named _preview. You will be able to browse Documentation from there that you just build.

This is how it will look like after the Doc is build:

Join and Help:

If you are looking forward to contribute to Atomic Host Docs, this URL contains the issues based on the topics that is required to be documented: https://github.com/projectatomic/atomic-host-docs/issues.

Mailing list:

• http://lists.projectatomic.io/mailman/listinfo/atomic
• http://lists.projectatomic.io/mailman/listinfo/atomic-devel

IRC: #atomic on Freenode server.