Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
# Generate beautiful word from markdown
Generate gazelle framework documentation from markdown files.
This project generates pdf, pdf with revision marks and a static website (using jekyll).
## Requirements
sudo apt-get install make git git-svn texlive-xetex pandoc ruby-dev
Clone using git-svn
mkdir gazelle-documentation
cd gazelle-documentation
git svn clone https://scm.gforge.inria.fr/authscm/<developername>/svn/gazelle/gazelle-documentation -T trunk -b branches -t tags
### Usage of git svn
To update your local copy
git svn rebase .
Once your work is ready, you can commit locally
git add filenames
git commit -m "blah blah" filenames
And then push all the local commits on the forge
git svn dcommit
## Generate documentation
install required software
from `gazelle-documentation` folder run:
$ make setup
# will install requirement on the computer
$ make
# will generate all the documents and the website
$ make view
# will generate all the documents and start jekyll
from a project folder run:
$ make release-notes
# will generate the PDF version of the release notes
Check target folder for results
## Folder structure
gazelle-documentation
|
+--tool1
| |--installation.md
| |--Makefile
| |--media/
| |--user.md
| |--release-notes/
| | |--1_0_0.md (one file per release, named with version identifier)
| |--target/ (Created at compile time)
|
+--tool2
| |--installation.md
| |--Makefile
| |--media/
| |--user.md
| |--release-notes/
| | |--1_0_0.md (one file per release, named with version identifier)
| |--target/ (Created at compile time)
|
|
+--Makefile.generic
+--Makefile
+--target/ (Created at compile time)
## Markdown files
The source files use the Markdown language.
To get fancy final documents, you need:
* A YAML header containing all the requested metadata (see YAML section)
* Use Relative paths to pictures (eg. *“./media/mypicture.jpg”*)
* Use Relative paths to point the resources located on the same platform (eg. If you need to reference a page in your tool, start the URL at *“/theTool”*)
The YAML header is used by Jekyll and pandoc to generate menus and front pages, make sure all the metadata are present and up-to-date. The *.md files must start with the YAML header.
Add the following header to your file (header of release note is generated in Jira, you only have to set the empty values):
---
title: User Manual or Installation Manual
subtitle: Tool name
author: Your name
function: Engineer
date: current date
toolversion: version of the tool the document applies to
version: version of the document
status: statut du document (Approved|Draft|For review)
reference: KER3-MAN-HEALTHLAB-(TOOL_NAME)_(USER|INSTALLATION)
customer: IHE-EUROPE
---
Example:
---
title: User Manual
subtitle: Order Manager
author: Anne-Gaëlle BERGE
function: Engineer
date: 02/09/2016
toolversion: 5.x
version: 2.01
status: Draft document
reference: KER3-MAN-HEALTHLAB-ORDER_MANAGER_USER
customer: IHE-EUROPE
---
# Links
http://pandoc.org/
[Pandoc installation package](https://github.com/jgm/pandoc/releases/tag/1.17.2)
http://blog.cigrainger.com/2014/07/pandoc-markdown.html