Github Documentation

11/1/2017 jobisoft/wikidoc: Create PDF le from github wiki documentation
jobisoft / wikidoc
Create PDF le from github wiki documentation
32 commits 1 branch 0 releases 1 contributor GPL-3.0
Branch: master New pull request Create new le Upload les Find le Clone or download
root Nicer TOC. Latest commit 6a5f637 on Mar 22, 2016
LICENSE Initial commit 2 years ago
README.md Nicer TOC. 2 years ago
wikidoc.py Remove trim again. 2 years ago
README.md
wikidoc
This python script allows to create nice looking PDF les from a github wiki, which can be used as oine/printable
documentation. It is a wrapper for pandoc and wkhtmltopdf.
Concept
All the information needed to congure wkhtmltopdf are stored in the wiki home le as html comments, so no additional
les/options are needed to generate the PDF. If the wiki home le is setup as needed, clone the wiki and run this script as
follows, to generate the PDF:
gitclonehttps://github.com/<user>/<repository>.wiki.git
/path/to/wikidoc.py<pathtowkhtmltopdf><pathtogithubwikirepository>
For this to work, the github wiki must be setup as github markdown, which allows html tags and thus html comments. The
wiki markdown les are converted via pandoc to html and are joined to one large html le, which is then converted to PDF
using wkhtmltopdf. The generated html le is not deleted, to be able to look up the html id tags created by pandoc, which
may be used to style the PDF. Writing the wiki in pure html in the rst place makes things a lot easier.
As an example, the documentation of the jTDC repository is generated by wikidoc from the jTDC wiki.
How it works
The following example home.md contains all possible wikidoc html comments:
<!WIKIDOCCONFIG
filenamedocumentation.pdf
pagesizeA4
margintop2cm
marginleft2cm
marginbottom2cm
marginright2cm
footerfontnameVerdana
footerfontsize6
footerspacing10
footerright[page]
WIKIDOCCONFIG>
https://github.com/jobisoft/wikidoc 1/4
<!WIKIDOCHTMLHEAD
<html>
<head>
<STYLEtype='text/css'>
html{fontfamily:Verdana,Geneva,sansserif;fontsize:13px;}
.covertitle{paddingtop:40%;textalign:right;fontsize:40px;}
.generated{fontsize:12px;}
table{bordercollapse:collapse;margin:1emauto1emauto;width:90%;border:1pxsolid#ccc;}
trtd:firstchild{borderright:1pxsolid#ccc;width:2.5cm!important;}
tabletr:firstchild{backgroundcolor:#ddd;}
tabletd{fontfamily:Verdana,Geneva,sansserif;fontsize:8pt;verticalalign:top;padding:5px;}
h1{pagebreakbefore:always;fontsize:26.6px;}
h2{margintop:3ex;fontsize:20px;}
h3{margintop:3ex;13.3px}
.breakbefore{pagebreakbefore:always;}
.wiki_only{display:none;}
</STYLE>
</head>
<body>
WIKIDOCHTMLHEAD>
<!WIKIDOCHTMLFOOT
</body>
</html>
WIKIDOCHTMLFOOT>
<!thefollowingWIKIDOCcommentsareoptional>
<!WIKIDOCCOVER
<divclass='covertitle'><b>Example</b>Documentation<br><spanclass='generated'>generatedfromgithubwiki:
###_WIKIDOC_GENDATE_###</span></div>
WIKIDOCCOVER>
<!WIKIDOCTOCXSL
<?xmlversion="1.0"encoding="UTF8"?>
<xsl:stylesheetversion="2.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:outline="http://wkhtmltopdf.org/outline"
xmlns="http://www.w3.org/1999/xhtml">
<xsl:outputdoctypepublic="//W3C//DTDXHTML1.0Strict//EN"
doctypesystem="http://www.w3.org/TR/xhtml1/DTD/xhtml1transitional.dtd"
indent="yes"/>
<xsl:templatematch="outline:outline">
<html>
<head>
<title>Contents</title>
<metahttpequiv="ContentType"content="text/html;charset=utf8"/>
<style>
h1{
textalign:left;
fontsize:26.6px;
fontfamily:verdana;
}
div{borderbottom:1pxdashedrgb(200,200,200);}
span{float:right;}
li{liststyle:none;}
ul{
fontsize:13px;
fontfamily:verdana;
}
ulul{fontsize:85%;}
ul{paddingleft:0em;}
ulul{paddingleft:1em;}
a{textdecoration:none;color:black;}
ul.toplevelli{marginbottom:1em;}
ul.sublevelsli{marginbottom:0em;}
ulli:lastchild{marginbottom:1em;}
</style>
</head>
<body>
<h1>Contents</h1>
<ulclass="toplevel"><xsl:applytemplatesselect="outline:item/outline:item"/></ul>
</body>
</html>
</xsl:template>
<xsl:templatematch="outline:item">
<li>
<xsl:iftest="(@title!='')and(@title!='Contents')">
<div>
<a>
<xsl:iftest="@link">
<xsl:attributename="href"><xsl:valueofselect="@link"/></xsl:attribute>
</xsl:if>
<xsl:iftest="@backLink">
<xsl:attributename="name"><xsl:valueofselect="@backLink"/></xsl:attribute>
</xsl:if>
<xsl:valueofselect="@title"/>
</a>
<span><xsl:valueofselect="@page"/></span>
</div>
</xsl:if>
<ulclass="sublevels">
<xsl:comment>addedtopreventselfclosingtagsinQtXmlPatterns</xsl:comment>
<xsl:applytemplatesselect="outline:item"/>
</ul>
</li>
</xsl:template>
</xsl:stylesheet>
WIKIDOCTOCXSL>
<!endofwikidocconfigsection>
<!WIKIDOCPDFONLY
<h1>###_WIKIDOC_TITLE_###</h1>
WIKIDOCPDFONLY>
Onlythistextisshownonthewikihomepage.Sincethetitleofthiswikifile(Home)isnot
partofthefileitself(thegithubwikigeneratesitfromthefilename),itwouldbemissinginthe
pdf.Toovercomethis,theWIKIDOCPDFONLYcommentcanbeused:Thecontentofthiscomment
isactuallyrenderedinthePDFandtheplaceholder###_WIKIDOC_TITLE_###isreplacedbyatitle
generatedfromthefilenameinthesamewaythegithubwikiisdoingit.However,youarefreeto
chooseadifferentnameforthepdfand/oradifferentheaderlevel(h2,h3...),orleaveitoutcompletely.
TheWIKIDOCPDFONLYcommentcanbeusedinallwikifiles,notjustthewikihomefile.
Comments usable in wiki home
WIKIDOC CONFIG: This required wikidoc comment contains a list of parameter denitions. All except "lename" will
be directly send as parameters to wkhtmltox (see documentation of wkhtmltox for a list of possible options). The
provided parameters are not veried by wikidoc. If the lename is missing, the default "wikidoc.pdf" will be used.
WIKIDOC HTMLHEAD and WIKIDOC HTMLFOOT: The wiki markdown les are converted to html with pandoc, joined
in the same order as listed on the github wiki and are put between the HTMLHEAD and HTMLFOOT segements
provided by these two required WIKIDOC comments. The HTMLHEAD may also contain a CSS STYLE section to
style the PDF.
WIKIDOC COVER: This is an optional comment. If present, it will create a cover page which is special to wkhtmltopdf
as it will never have any header or footer. The COVER comment may only contain html (no markdown allowed!) and
supports all available placeholder substitutions (for example ###WIKIDOC_GENDATE###).
WIKIDOC TOCXSL: This is an optional comment. If present, a table of contents will be added to the PDF, after the
cover and before the actual document. The TOC is completely dened by the provided XSL. Any provided
wkhtmltopdf parameter for the toc section will be ignored.
Comments usable in all wiki les
WIKIDOC PDFONLY: The html content (no markdown allowed!) of this comment will be redered in the PDF. The
original purpose was to provide a exibel solution to add a header to each wiki le (see botttom of example home.md).
However, it can be used to provide any html content for the PDF, which might not be supported by the github wiki
markdown. For example complex tables: A simple table could be designed for the wiki, which has a CSS class which
hides it in the PDF and the PDFONLY contains a more complex table for the PDF.
If the PDFONLY section is given a name as in the following example, the section will also be generated as a PNG, which
can be used in the wiki, to overcome limitations of the github markdown. The PNG will get its name from the section name
and ist stored inside the wiki repository in a folder called generatedimages. That folder must exist.
<!WIKIDOCPDFONLYexamplewithname
<tableCELLPADDING="3"
...
</table>
WIKIDOCPDFONLY>

Github Documentation

Diunggah oleh

Informasi Dokumen

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

Github Documentation

Diunggah oleh

Hak Cipta:

Format Tersedia

11/1/2017 jobisoft/wikidoc: Create PDF le from github wiki documentation

Create PDF le from github wiki documentation

32 commits 1 branch 0 releases 1 contributor GPL-3.0

root Nicer TOC. Latest commit 6a5f637 on Mar 22, 2016

LICENSE Initial commit 2 years ago

README.md Nicer TOC. 2 years ago

wikidoc.py Remove trim again. 2 years ago

Comments usable in wiki home

Comments usable in all wiki les

Anda mungkin juga menyukai