Purpose
giblish is used to convert a source directory tree containing AsciiDoc files to a destination directory tree containing the corresponding html or pdf files and add a handy index page for the converted files.
If the source directory tree is part of a git repository, giblish can generate separate html/pdf trees for branches and/or tags that match a user specified regexp (see examples below).
Dependencies and credits
Giblish is basically a wrapper (with some extra candy) around the awesome asciidoctor and asciidoctor-pdf projects. Thank you @mojavelinux and others for making these brilliant tools available!!
Installation
gem install giblish
Some random notes
When using giblish for generating docs the following applies:
-
giblish will overwrite files with the same name in the destination directory.
-
make sure that the git working tree and index of the source git repo are clean when generating docs from a git repo.
-
giblish will make explicit check-outs of all the branches or tags that matches the selection criteria. The working dir of the source git repo will thus have the last branch that giblish checked-out as the current branch after doc generation.
Usage Examples
giblish -h
giblish my_src_root my_dst_root
The above will convert all .adoc or .ADOC files under the dir my_src_root
to
html and place the resulting files under the my_dst_root
dir. An index page
named index.html
is generated in the my_dst_root
dir containing links and
some info about the converted files.
The default asciidoctor css will be used in the html conversion.
giblish -r ./path/to/my/resources -s mylayout my_src_root my_dst_root
The above will convert all .adoc or .ADOC files under the dir my_src_root
to
html and place the resulting files under the my_dst_root
dir. An index page
named index.html
is generated in the my_dst_root
dir containing links and
some info about the converted files.
A css named mylayout.css must be found in the dir
<working_dir/path/to/my/resources/css
. The resulting html files will link
to this css. Fonts and images used from the css must be found under
<working_dir/path/to/my/resources/fonts
and
<working_dir/path/to/my/resources/images
respectively.
giblish -g "feature" my_src_root my_dst_root
The above will check-out all branches matching the regexp "feature" and convert
the .adoc or .ADOC files under the dir my_src_root
to html and place the
resulting files under the my_dst_root/<branch_name>
dir.
An index page named index.html
is generated in each my_dst_root/<branch_name
dir containing links and some info about the converted files.
A summary page containing links to all branches will be generated directly in
the my_dst_root
dir.
Assuming you have cloned this git repo to ~/github/giblish
you can do:
giblish -g "master" -r ~/github/giblish/resources ~/github/giblish my_dst_root
The above will check-out all branches matching the regexp "master" and convert
the .adoc or .ADOC files under the dir my_src_root
to html and place the
resulting files under the my_dst_root/<branch_name>
dir.
An index page named index.html
is generated in each my_dst_root/<branch_name
dir containing links and some info about the converted files.
A summary page containing links to all branches will be generated directly in
the my_dst_root
dir.
Assuming you have cloned this git repo to ~/github/giblish
you can do:
giblish -f pdf -g "master" -r ~/github/giblish/resources ~/github/giblish my_dst_root
The above will check-out all branches matching the regexp "master" and convert
the .adoc or .ADOC files under the dir my_src_root
to pdf and place the
resulting files under the my_dst_root/<branch_name>
dir.
An index page named index.pdf
is generated in each my_dst_root/<branch_name
dir containing links and some info about the converted files.
A summary page containing links to all branches will be generated directly in
the my_dst_root
dir.
giblish can be used to inject a tree of html docs suitable for serving via a web server (e.g. Apache). Below is an example how to create such a tree. If you combine this with a server side git hook that invokes this script after push, you will have a way of auto publish your latest documents and/or documents at specific git tags. In principle a poor-mans document managing system.
Assumptions:
-
You have a running web server that serves pages from directory root
/var/www/html
-
You want to access the generated docs from http://your_web_site.com/proddocs
-
The git repo containing the source docs has its working dir at
~/gh/myrepo
-
You only want to publish the documents in the subfolder
common/Documents
in your git repo. -
You want to use your own css named
mylayout.css
that internally references fonts and images using relative paths. -
You have the css and its referenced fonts and images in subfolders of the git repo at
common/resources/css common/resources/fonts common/resources/images
-
You want to publish the documentation as it looked for your release tags myprod-v1.0-final, myprod-v2.0-final, …
giblish -t "-final$" -r ~/gh/myrepo/common/resources -s mylayout -w /var/www/html ~/gh/myrepo/common/Documents /var/www/html/proddocs
The above will create a tree of html docs under /var/www/html/proddocs
. Each
tag will get its own subdir (e.g. /var/www/html/proddocs/myprod_v1.0_final
).
The css and referenced assets will be copied to a 'web_assets' dir for each
subdir and also to the …/proddocs dir.
The -w
switch above will strip the /var/www/html
from the css link so that
the paths to the css will be correct in the context of the serving of the
pages via the web server.