source: branches/branch-1.5/docs/contribute/doc.rst @ 736

Last change on this file since 736 was 725, checked in by djay, 9 years ago

Fix issue with rst files displayed from Trac. Fix strings to be translated. Always use the same string in all messages.

  • Property svn:keywords set to Date Author
  • Property svn:mime-type set to text/plain
File size: 4.6 KB
Line 
1.. _contribute_doc:
2
3.. include:: <xhtml1-lat1.txt>
4.. include:: <xhtml1-symbol.txt>
5
6Contribute documentation
7========================
8
9ZOO Documentation is a collaborative process managed by the ZOO developers. Anybody is welcome to contribute to the ZOO-Project documentation. Please consider the following instructions before doing so.
10
11General information
12------------------------
13
14Heading syntaxe
15...............
16
17Tere are various title heading used in the documentation, when you
18create a new document, you're invited to follow the following heading
19underline syntaxe:
20
21 * for Heading 1, use ``=``,
22 *  for Heading 2, use ``-``,
23 *  for Heading 3, use ``.``,
24 *  for Heading 4, use ``*``,
25 *  for Heading 5, use ``#``.
26 
27
28For new comers
29..........................
30
31New users are encouraged to contribute documentation using the following ways:
32
33* Download the ZOO-Project svn, edit the documentation files
34  located /docs directory and share the modifications through a new
35  ticket set to 'Documentation' tracker
36 
37* Create a wiki page containg new or corrected documentation text, and create a new ticket to report its creation.
38
39The ZOO developers responsible for the documentation will then review the contributions to add them into the official docs.
40
41For registered developers
42........................................
43
44The current structure of the ZOO Project documentation process is for
45developers with :ref:`SVN <svn>` commit access to maintain their
46documents in reStructuredText format, and therefore all documents live
47in the /docs directory in SVN.  The `Sphinx
48<http://sphinx.pocoo.org/>`__ documentation generator is used to
49convert the reStructuredText files to html, and the live website is
50then updated on an hourly basis.
51
52
53Installing and using Sphinx
54---------------------------
55
56On Linux
57.................
58
59* Make sure you have the Python dev and setuptools packages installed. For example on Ubuntu:
60
61   ::
62
63       sudo apt-get install python-dev
64       sudo apt-get install python-setuptools
65
66* Install sphinx using easy_install:
67
68   ::
69
70       sudo easy_install Sphinx==1.3.1
71       
72   .. note::
73   
74      Make sure you install Sphinx 1.3.1 or more recent.
75     
76* Checkout the /docs directory from SVN, such as:
77
78   ::
79 
80       svn checkout http://svn.zoo-project.org/svn/trunk zoo-project     
81
82* To process the docs, from the ZOO /docs directory, run:
83
84   ::
85
86       make html
87
88   or
89
90   ::
91
92       make latex
93
94   The HTML output will be written to the build/html sub-directory.
95
96.. note::
97
98    If there are more than one translation, the above commands will automatically
99    build all translations.
100
101
102On Mac OS X |trade|
103..................................
104
105* Install sphinx using easy_install:
106
107   ::
108
109       sudo easy_install-2.7 Sphinx==1.3.1
110       
111   .. note::
112   
113      Make sure you install Sphinx 1.3.1 or more recent.
114
115* Install `MacTex <http://www.tug.org/mactex/2009/>`__ if you want to build pdfs
116
117* Checkout the /docs directory from SVN, such as:
118
119   ::
120 
121       svn checkout http://svn.zoo-project.org/svn/trunk zoo-project
122
123* To process the docs, from the ZOO /docs directory, run:
124
125   ::
126
127       make html
128
129   or
130
131   ::
132
133       make latex
134
135   The HTML output will be written to the build/html sub-directory.
136
137
138On Windows |trade|
139................................
140
141* Install `Python 2.X <http://www.python.org/>`__
142* Download `setuptools <http://pypi.python.org/pypi/setuptools#windows>`__
143* Make sure that the ``C:/Python2X/Scripts`` directory is your path
144* Execute the following at commandline:
145
146   ::
147
148       easy_install Sphinx==1.3.1
149
150   ...you should see message: "Finished processing dependencies for Sphinx"
151
152   .. note::
153   
154      Make sure you install Sphinx 1.3.1 or more recent.  See note above.
155     
156* Install `MiKTeX <http://miktex.org>`__ if you want to build pdfs
157     
158* Checkout the /docs directory from SVN, such as:
159
160   ::
161 
162       svn checkout http://svn.zoo-project.org/svn/trunk zoo-project
163     
164* Inside the /docs directory, execute:
165
166   ::
167
168       make html
169
170   or
171
172   ::
173
174       make latex
175
176   The HTML output will be written to the _build/html sub-directory.
177
178
179reStructuredText Reference Guides
180***************************************
181
182The following resources are considered as useful for editing and creating new ZOO-Project documentation files.
183
184- Docutils `Quick reStructuredText <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`__
185- Docutils `reStructuredText Directives <http://docutils.sourceforge.net/docs/ref/rst/directives.html>`__
186- Sphinx's `reStructuredText Primer <http://sphinx.pocoo.org/rest.html>`__
187- search Sphinx's `mailing list <http://groups.google.com/group/sphinx-dev>`__
Note: See TracBrowser for help on using the repository browser.

Search

Context Navigation

ZOO Sponsors

http://www.zoo-project.org/trac/chrome/site/img/geolabs-logo.pnghttp://www.zoo-project.org/trac/chrome/site/img/neogeo-logo.png http://www.zoo-project.org/trac/chrome/site/img/apptech-logo.png http://www.zoo-project.org/trac/chrome/site/img/3liz-logo.png http://www.zoo-project.org/trac/chrome/site/img/gateway-logo.png

Become a sponsor !

Knowledge partners

http://www.zoo-project.org/trac/chrome/site/img/ocu-logo.png http://www.zoo-project.org/trac/chrome/site/img/gucas-logo.png http://www.zoo-project.org/trac/chrome/site/img/polimi-logo.png http://www.zoo-project.org/trac/chrome/site/img/fem-logo.png http://www.zoo-project.org/trac/chrome/site/img/supsi-logo.png http://www.zoo-project.org/trac/chrome/site/img/cumtb-logo.png

Become a knowledge partner

Related links

http://zoo-project.org/img/ogclogo.png http://zoo-project.org/img/osgeologo.png