Re: [atomic-devel] Doc format?

[Matt Micene <nzwulfin gmail com>]

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

git github com:nzwulfin/atomic-site.git  Check out the adoc branch.

The only 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

On Fri, Mar 11, 2016 at 10:34 AM, Colin Walters <walters verbum org> wrote:

On Fri, Mar 4, 2016, at 06:59 PM, Josh Berkus wrote:

> One of the reasons I'm asking is that if most things are markdown, we
> can consider using ReadTheDocs.  But if we've got a lot of ASCIIDocs, we
> can't.

I'd say there is two levels here: Global docs and per-project docs.  We
should cross link with both.

Some consensus seems to be around asciidoc for global docs, so we'd have:

docs.projectatomic.io as Asciidoc

In particular make these *consumer* (administrator/developer-as-user) focused docs.

As an example, I'd like to have a "mirroring content" section that would cross several
components (RPM, Docker, OSTree).

But that then can call out into e.g. the atomic-reactor or rpm-ostree docs on readthedocs
for some details.  Or if a project chooses to use Asciidoc internally, we can host those
docs too on docs.projectatomic.io/projectname as a readthedocs.org equivalent, or
just concatenate the project docs as a section in the global docs?