-
Notifications
You must be signed in to change notification settings - Fork 19
/
README_DOCUMENTATION_GUIDELINES
184 lines (139 loc) · 7.08 KB
/
README_DOCUMENTATION_GUIDELINES
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
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
==================
GENERAL GUIDELINES
==================
#. **Installation Manual**
#. **User's Guide**
#. **Developer's Reference Manual**
#. **User's Scientific Report**
Document Guidelines
===================
The purpose of these document guidelines is to create a coherent set of documents
that clarify the functionality of |TVB|.
These documents are meant to be readily available not only to the development
team members, but also to management and other interested parties.
Here we try to provide specific guidelines for each of the documents,
to suggest responsibility for their creation and maintenance, and to describe
how the documents are/should be interrelated.
General Guidelines
==================
Accessibility
-------------
Documents developed for the |TVB| will be organized and made available for
downloading via the SVN repository: https://repo.thevirtualbrain.org/svn/tvb/trunk/tvb-documentation
or via GitHub https://github.com/the-virtual-brain/tvb-documentation.
Each of the manuals/docs presented below has its own folder in this structure,
so all files strictly related to that document (images, styles, ...) should be placed into
the corresponding folder.
File format
-----------
Documents should be available in a simple text format. We recommend that they are
written in rst (reStructuredText) and based on a set of templates
RST was chosen because:
- it is simple;
- it can produce both print and web documentation;
- it is the format generated by the python compatible auto-documentation tool SPHINX.
For more details about the rst style format, read the rst quick reference at:
** http://docutils.sourceforge.net/docs/user/rst/quickref.html **
Documents Structure
------------------
In order to have a consistent structure and format for all documents it's important to follow
some rules while writing docs:
1. Each manual/document must have a MAIN document where other RST files can be included.
2. Because we have some documents that include other RST files, it's important to have the same "scheme"
for chapter identification. In this respect here is the order of the characters to be used
while defining chapters/sub-chapters/paragraphs ...
a) ========================
b) ------------------------
c) ........................
d) ~~~~~~~~~~~~~~~~~~~~~~~~
e) ************************
f) ++++++++++++++++++++++++
3. After any change in TVB documents, please generate at least PDF version to ensure there is no
error in the document. Next chapter explains how to do that.
Screenshots
-----------
Most of TVB documents include images and screenshots of the web interface. This is ok,
but we have to consider a few aspects when introducing images in our documentation:
- image size/resolution: please be aware of the size of the images you are using into documentation.
In order to introduce them into documentation, any framework/software has to adjust them, which
means processing time and quality reduction.
- image format: current recommended format for storing/using images is png but if there are
cases when you don't need a high level of details jpg format can be used too.
IMPORTANT:
In case of UserGuide, from which we automatically generate Online-Help please use JPG format
for screenshots. Also, if you have any tools please try to pre-process these images to reduce their
size as much as possible, without loosing details.
This is important because it reduces the time to show online help into client browser.
Create PDF & HTML
-----------------
At build time for all TVB manuals we generate appropriate PDF files and from some parts of
User's Guide (related to UI) generate online-help. As a result TVB release (zip files)
contains into /docs folder all PDF files. HTML content is placed in a folder that
makes it available through web interface.
Most probably you don't want to create a full TVB distribution, only to check if your
document is ok. Quick builds:
1. To generate PDFs
$ make latex
$ cd _build/latex
$ make
A pdf for each manual is created in _build/latex
2. To generate the HTML site
$ make html
Files in _build/html
Simulator Documentation
-----------------------
The entire Simulator documentation can be found in trunk\tvb\simulator\doc. Mainly here you can see
the RST files with texts and all necessary images are placed into ./img folder.
!!! Important: but at this moment images are not generated automatically at build time. So for any
chage in the documentation or code we have to generate them and commit on SVN using:
a) to generate class diagrams please run: class_diagrams.sh
b) to generate model images please run : python generate_model_phase_plane_images.py
and do not forget to commit on svn images used into RST files.
To check, for missing images you can try to generate PDF for tvb.simulator.rst (with rst2pdf)
and look for missing image errors.
Available Documents
===================
Below are descriptions of the recommended development documents with guidelines on content.
Using a consistent format will make it easier to compile the documents and
maintain them as a coherent body of documentation.
Installation Manual
---------------------
Purpose: This manual should provide detailed description about the steps
to be followed to download & install TVB.
Contents: Installation steps / instructions.
Created and Maintained by: Lead developer(s) and Web designer.
File: manuals/InstallationManual/InstallationManual.rst
User's Guide
------------
Purpose:
Describes the function, interfaces and usage of the software.
Describes the overall structure of the |TVB| flow.
Contents: Web interface description and simulation examples.
Created and Maintained by: Framework and Scientific Development teams / Web designer
File: manuals/UserGuide/UserGuide.rst
Developer's Reference Manual
-----------------------
Purpose: Describes the function and architecture of |TVB| as a application.
Contents: Code documentation + command-line examples (?)
Created and Maintained by: Framework and Scientific Development teams
File: manuals/DeveloperReference/DeveloperReferenceManual.rst
Handouts
------------------------
Purpose: To provide a more detailed and comprehensive description of |TVB|:
and test cases with clinical/scientific relevance.
The handouts are updated before a new |TVB| wsorkshop.
Created and Maintained by: Paula Sanz-Leon.
File: manuals/ScientificReport/UserScientificReport.rst
Images: manuals/ScientificReport/images
As general rules:
................
- IMAGES
* Format: .svg, .jpeg or .png format
* It is strongly encouraged to have the code for any figure resulting from a
simulation/ an analysis. We should offer reproducible figures.
- REFERENCES
* MUST be included in manuals/ScientificReport/sci.report.bib.rst (see the example below)
.. _FitzHugh 1961:
.. [FH_1961] FitzHugh, R., *Impulses and physiological states in theoretical models of nerve membrane*, Biophysical Journal 1: 445, 1961.
* To use the reference within any of the sci.report files use the citation label with a trailing underscore (see the example below)
Here is a citation reference: (`FitzHugh 1961`_).