giblish 0.2.2 → 0.2.3
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.adoc +83 -1
- data/lib/giblish/version.rb +1 -1
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 10f9c75389bc10dda386f5cd9cfb0855f62e06ca
|
|
4
|
+
data.tar.gz: fe089e9bff2e72e3eccff4e34f011cc70c4d88de
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 804bfc3f306c990d510039667041115854a2a7ab4853b39fd4139e7170e2b718ed1229a039c6212c0a5fd6a622c93d81ea24ca029cc2e7ca94d90cd87b13b87c
|
|
7
|
+
data.tar.gz: 06dc7ba624c02f6efae6ac2a34da8ee46d3f9615d0bf6264af357fe83f60398bf64ff89d7f28e1e45197f081f1268ee323397c6bc0ef8d3fda70247a43d28167
|
data/README.adoc
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
Generate docs from asciidoc files in a git repo
|
|
3
3
|
|
|
4
4
|
== Purpose
|
|
5
|
+
|
|
5
6
|
giblish is used to convert a source directory tree containing AsciiDoc files to
|
|
6
7
|
a destination directory tree containing the corresponding html or pdf files
|
|
7
8
|
and add a handy index page for the converted files.
|
|
@@ -20,6 +21,18 @@ making these brilliant tools available!!
|
|
|
20
21
|
|
|
21
22
|
gem install giblish
|
|
22
23
|
|
|
24
|
+
== Some random notes
|
|
25
|
+
|
|
26
|
+
When using giblish for generating docs the following applies:
|
|
27
|
+
|
|
28
|
+
* giblish *will overwrite* files with the same name in the destination directory.
|
|
29
|
+
* make sure that the git working tree and index of the source git repo are clean
|
|
30
|
+
when generating docs from a git repo.
|
|
31
|
+
* giblish will make explicit check-outs of all the branches or tags that matches
|
|
32
|
+
the selection criteria. The working dir of the source git repo will thus have
|
|
33
|
+
the last branch that giblish checked-out as the current branch after doc
|
|
34
|
+
generation.
|
|
35
|
+
|
|
23
36
|
== Usage Examples
|
|
24
37
|
|
|
25
38
|
.Get available options
|
|
@@ -55,7 +68,7 @@ to this css. Fonts and images used from the css must be found under
|
|
|
55
68
|
`<working_dir/path/to/my/resources/images` respectively.
|
|
56
69
|
====
|
|
57
70
|
|
|
58
|
-
.Generate
|
|
71
|
+
.Generate html from multiple git branches
|
|
59
72
|
====
|
|
60
73
|
giblish -g "feature" my_src_root my_dst_root
|
|
61
74
|
|
|
@@ -69,3 +82,72 @@ dir containing links and some info about the converted files.
|
|
|
69
82
|
A summary page containing links to all branches will be generated directly in
|
|
70
83
|
the `my_dst_root` dir.
|
|
71
84
|
====
|
|
85
|
+
|
|
86
|
+
.Generate html from giblish git repo using giblish css
|
|
87
|
+
====
|
|
88
|
+
Assuming you have cloned this git repo to `~/github/giblish` you can do:
|
|
89
|
+
|
|
90
|
+
giblish -g "master" -r ~/github/giblish/resources ~/github/giblish my_dst_root
|
|
91
|
+
|
|
92
|
+
The above will check-out all branches matching the regexp "master" and convert
|
|
93
|
+
the .adoc or .ADOC files under the dir `my_src_root` to html and place the
|
|
94
|
+
resulting files under the `my_dst_root/<branch_name>` dir.
|
|
95
|
+
|
|
96
|
+
An index page named `index.html` is generated in each `my_dst_root/<branch_name`
|
|
97
|
+
dir containing links and some info about the converted files.
|
|
98
|
+
|
|
99
|
+
A summary page containing links to all branches will be generated directly in
|
|
100
|
+
the `my_dst_root` dir.
|
|
101
|
+
====
|
|
102
|
+
|
|
103
|
+
.Generate pdf from giblish git repo using the giblish pdf theme
|
|
104
|
+
====
|
|
105
|
+
Assuming you have cloned this git repo to `~/github/giblish` you can do:
|
|
106
|
+
|
|
107
|
+
giblish -f pdf -g "master" -r ~/github/giblish/resources ~/github/giblish my_dst_root
|
|
108
|
+
|
|
109
|
+
The above will check-out all branches matching the regexp "master" and convert
|
|
110
|
+
the .adoc or .ADOC files under the dir `my_src_root` to pdf and place the
|
|
111
|
+
resulting files under the `my_dst_root/<branch_name>` dir.
|
|
112
|
+
|
|
113
|
+
An index page named `index.pdf` is generated in each `my_dst_root/<branch_name`
|
|
114
|
+
dir containing links and some info about the converted files.
|
|
115
|
+
|
|
116
|
+
A summary page containing links to all branches will be generated directly in
|
|
117
|
+
the `my_dst_root` dir.
|
|
118
|
+
====
|
|
119
|
+
|
|
120
|
+
.Advanced usage; Publish a static html site from a git repo
|
|
121
|
+
====
|
|
122
|
+
giblish can be used to inject a tree of html docs suitable for serving via a web
|
|
123
|
+
server (e.g. Apache). Below is an example how to create such a tree. If you
|
|
124
|
+
combine this with a server side git hook that invokes this script after push,
|
|
125
|
+
you will have a way of auto publish your latest documents and/or documents at
|
|
126
|
+
specific git tags. In principle a poor-mans document managing system.
|
|
127
|
+
|
|
128
|
+
Assumptions:
|
|
129
|
+
|
|
130
|
+
* You have a running web server that serves pages from directory root
|
|
131
|
+
`/var/www/html`
|
|
132
|
+
* You want to access the generated docs from http://your_web_site.com/proddocs
|
|
133
|
+
* The git repo containing the source docs has its working dir at `~/gh/myrepo`
|
|
134
|
+
* You only want to publish the documents in the subfolder `common/Documents` in
|
|
135
|
+
your git repo.
|
|
136
|
+
* You want to use your own css named `mylayout.css` that internally references
|
|
137
|
+
fonts and images using relative paths.
|
|
138
|
+
* You have the css and its referenced fonts and images in subfolders
|
|
139
|
+
of the git repo at `common/resources/css common/resources/fonts common/resources/images`
|
|
140
|
+
* You want to publish the documentation as it looked for your release tags
|
|
141
|
+
myprod-v1.0-final, myprod-v2.0-final, ...
|
|
142
|
+
|
|
143
|
+
giblish -t "-final$" -r ~/gh/myrepo/common/resources -s mylayout -w /var/www/html ~/gh/myrepo/common/Documents /var/www/html/proddocs
|
|
144
|
+
|
|
145
|
+
The above will create a tree of html docs under `/var/www/html/proddocs`. Each
|
|
146
|
+
tag will get its own subdir (e.g. `/var/www/html/proddocs/myprod_v1.0_final`).
|
|
147
|
+
The css and referenced assets will be copied to a 'web_assets' dir for each
|
|
148
|
+
subdir and also to the .../proddocs dir.
|
|
149
|
+
|
|
150
|
+
The `-w` switch above will strip the `/var/www/html` from the css link so that
|
|
151
|
+
the paths to the css will be correct in the context of the serving of the
|
|
152
|
+
pages via the web server.
|
|
153
|
+
====
|
data/lib/giblish/version.rb
CHANGED