[librecat-dev] Librecat API documentation

[Patrick Hochstenbach]

I fear I need to build a new development machine ;). On CentOS 6.8 the Pandoc is only 1.9 and even the ghc is outdated to build a more recent version.

> On 6 Feb 2017, at 12:07, Jakob Voß <Jakob.Voss at gbv.de> wrote:
> 
> 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/
> _______________________________________________
> librecat-dev mailing list
> - send list mails to librecat-dev at lists.uni-bielefeld.de
> - to unsubscribe or change options, visit https://lists.uni-bielefeld.de/mailman2/cgi/unibi/listinfo/librecat-dev
> - project website: http://librecat.org/