Re: [atomic-devel] Proposal - Moving container development tools docs to the Asciidoc format

[Aaron Weitekamp <aweiteka redhat com>]

On Mon, May 23, 2016 at 6:09 PM, Matt Micene <nzwulfin gmail com> wrote:

On 05/23/2016 02:44 PM, Josh Berkus wrote:

On 05/23/2016 06:03 AM, Preeti Chandrashekar wrote:

Hi All,

In line with our ongoing efforts at streamlining the docs process, and
in order to ensure better upstream-downstream coordination, we
are proposing to move to the Asciidoc format for docs related to
container development tools in Project Atomic.

I'm happy for this to be our default, but I'm concerned about making
existing projects port their docs.  For one thing, at least a couple of
projects make use of readthedocs.org, which requires a different format.

I ran the current set of docs through pandoc and spit out asciidoc versions a few weeks ago.  I didn't want to make this an official PR at this point but a place to look at the results.

https://github.com/nzwulfin/atomic-site/tree/adoc

I have registry docs rendering html[1] using asciibinder[2]. I would recommend the addition of asciibinder only if you need multiple content set and/or branded distributions of the docs. I think the projectatomic template work I did[3] would be useful to this effort regardless.

[1] http://docs.projectatomic.io/registry/
[2] http://www.asciibinder.org/

[3] look for "atomic" files: https://github.com/openshift/openshift-docs/tree/master/_templates

​

 

Things that you need to know:
* authoring an AsciiDoc document that Middleman (and Jekyll for that matter) still wants a YAML front matter block to recognize it as a doc / post.  The blocks here are blank, but could include title: like before.  It doesn't seem to matter to basic operations.
* the current rendering for AsciiDoc isn't particularly pretty.  The Table at the top of the Getting Started Guide, for example, looks like tab delimited text.  Section headings also get pretty small quickly.  So we'd need to explore rendering.

Otherwise, that branch is a functional starting point.  Folks more familiar with how we're using Middleman can probably chime in on the use of vars defined in the front matter block and if those need to be added back in.

Cheers,
- Matt M