Example of newer document writing for Fedora-docs

tldr; How to build documentation using asciidoc and pintail

If you have read the FAD report, you should have know that we are moving away from publican flow and using pintail to build the asciidoc. In this post we will be building a example doc.

I suppose that you are using Fedora, if you are using any other GNU/Linux you need to install most of them from source.

So let’s get a overview of how this thing work.

We write docs in Asciidoc (.adoc) format then convert into mallard (.page) format using the asciidoctor-mallard tool then convert (build) them into html using pintail which is a two step process. We can make it a one step process using the pintail-asciidoc plugin which does the same thing in the background.

so let’s build docs using the first way ie without using the plugin. For this we need to have 2 tools installed asciidoctor-mallard and pintail which are available in my copr, you can do them in this manner.

sudo dnf copr enable dhanvi/asciidoctor-mallard

sudo dnf install rubygem-asciidoctor-mallard

sudo dnf copr enable dhanvi/pintail

sudo dnf install pintail

and then we get started with writing, let’s create a new directory and write a example doc

mkdir asciidoc-example

cd asciidoc-example

touch example.adoc

Open example.adoc (note the format .adoc -> asciidoc) and paste these simple asciidoc lines. Fedora-docs team and my mentor Zach are working the guidelines for writing in asciidoc more details here https://pagure.io/documentation-guide/issues

= Document Title
Doc Writer <doc@example.com>
:doctype: book
:source-highlighter: coderay
:listing-caption: Listing

A simple http://asciidoc.org[AsciiDoc] document.

== Introduction

A paragraph followed by a simple list with square bullets.

[square]
* item 1
* item 2

Now let’s convert them into mallard (.page) using asciidoctor-mallard

asciidoctor-mallard example.adoc

ignore any warning, the asciidoctor-mallard needs some fixes.

You will find a example.page created when you run the above command, here is the contents of the example.page file.

<?xml version="1.0" encoding="UTF-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" xml:lang="en" type="topic" id="example">
<info>
<credit type="author">
<name>Doc Writer</name>
<email>doc@example.com</email>
</credit>
</info>
<title>Document Title</title>
A simple 		<link href="http://asciidoc.org">AsciiDoc</link> document.
<section id="_introduction">
<title>Introduction</title>
A paragraph followed by a simple list with square bullets.
		<list>
<item>
item 1
</item>
<item>
item 2
</item>
</list>
</section>
</page>

now we convert the mallard (.page) to html using the pintail

pintail init

pintail build

pintail init creates the config file which can be used for the configuration of how the pintail builds the docs and adding plugins etc..

pintail build creates the html files inside the pintail/build directory. And here is the screenshot of how the files looks like

I know it need some good template, we will work on it after we finish the continuous deployment. So this is how a basic asciidoc is build using the pintail.

Let’s do the same thing using the pintail-asciidoc plugin you need to first install it and packages mentioned above also.

sudo dnf copr enable dhanvi/pintail-asciidoc

sudo dnf install python-pintail-asciidoc

we create a new directory and do the above steps again but you need not do two steps and just need to do pintail build every time.

mkdir asciidoc-example2

cd asciidoc-example2

touch example.adoc

open the example.adoc in your favorite doc  and add the same lines as above. and do these steps.

pintail init

echo "plugins = pintail.asciidoc" >> pintail.cfg

pintail build

you need to do the init and echo only one time after every changes to the example.adoc you just need to do pintail build. The echo command say’s to use the plugin which we installed to pintail to build the asciidoc (.adoc) files.

So that’s all for the post and the next goal for me is to hack on git hooks and work on continuous deployment 🙂