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

[Josh Berkus <jberkus redhat com>]

On 05/24/2016 07:01 AM, Brian (bex) Exelbierd wrote:
> On 05/24/2016 12:09 AM, Matt Micene 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
>>
>>
>> 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.
> 
> I thought the goal with docs.projectatomic.io was to have each project
> provide a container that delivered html for the site.

That's correct.  Infra is still a WIP, though.


-- 
--
Josh Berkus
Project Atomic
Red Hat OSAS