Newer
Older
# 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
mkdir gazelle-user-documentation
cd gazelle-user-documentation
git clone git@gitlab.inria.fr:gazelle/documentation/gazelle-user-documentation.git
You shall have previously defined your GitLab user: git config --global user.email "email@example.com"
Once your work is ready, you can commit locally
git add filenames
git commit -m "blah blah" filenames
## Generate documentation
install required software
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
$ 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.
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.