[librecat-dev] Librecat API documentation

Jakob Voß Jakob.Voss at gbv.de
Mon Feb 6 12:07:03 CET 2017


Patrick wrote:

> I'll check it out further monday how we want to integrate
 > this into the LibreCat wiki!

I just added docs/ and wiki/ to .gitignore so gh-pages and wiki can be 
checked out as subfolders in your local LibreCat working tree:

$ git clone -b gh-pages  git at github.com:LibreCat/LibreCat.git docs
$ git clone git at github.com:LibreCat/LibreCat.wiki.git wiki

For gh-pages I added a sample HTML template. The current pages have been 
generated with:

$ pod2pandoc lib/ docs/ --standalone \
   --template docs/template.html --css template.css

Much customization can already be done without any knowledge of Perl or 
Pandoc. Additional Template variables can be added with options 
--default-meta (JSON or YAML) or --metadata (single fields).


For the LibreCat wiki the API documentation could either be copied to 
the wiki or the wiki could be copied to GitHub pages, pandoc supports 
both conversions.

The only thing that does not work perfect is title of pages in the wiki. 
Colons in module names (e.g. "Pod::Pandoc") are converted to "-" which 
is displayed as space:

https://github.com/nichtich/Pod-Pandoc/wiki/Pod-Pandoc

But this is only cosmetics.

Cheers
Jakob

> I have finished a Perl module to convert POD to anything supported by
> pandoc document converter:
>
> https://github.com/nichtich/Pod-Pandoc
>
> As example, the documentation of Pod::Pandoc is pushed to a GitHub wiki
> and to Read The Docs with each commit at the master branch:
>
> https://github.com/nichtich/Pod-Pandoc/wiki
> http://pod-pandoc.readthedocs.io/en/latest/Pod-Pandoc.html
>
>
> Using pod2pandoc I created Librecat API documentation in HTML and put it
> into the gh-pages branch:
>
> http://librecat.org/LibreCat/
>
> There is no HTML template and CSS yet but this is supported by pandoc:
>
> http://pandoc.org/MANUAL.html#templates
>
> Before investing more time in this I'd like to know some more
> requirements (possibly as GitHub issue).
>
> Cheers
> Jakob
>
> P.S.: Read The Docs also creates a PDF but this might better be done
> directly via pandoc:
>
> http://readthedocs.org/projects/pod-pandoc/downloads/pdf/latest/
>
> P.S: Same can be used for updating Catmandu documentation and intermix
> it with the existing content from Catmandu wiki.

-- 
Jakob Voß <jakob.voss at gbv.de>
Verbundzentrale des GBV (VZG) / Common Library Network
Platz der Goettinger Sieben 1, 37073 Göttingen, Germany
+49 (0)551 39-10242, http://www.gbv.de/


More information about the librecat-dev mailing list