giblish 0.2.2 → 0.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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