source: trunk/docs/development/documentation.txt @ 317

Last change on this file since 317 was 313, checked in by jmckenna, 13 years ago

change header

  • Property svn:keywords set to HeadURL Date Author Id Rev
File size: 3.8 KB
Line 
1.. _documentation_development:
2
3Documentation Development Guide
4===============================
5
6:Authors: Nicolas Bozon, Gérald Fenoy, Jeff McKenna
7:Last Updated: $Date: 2011-08-11 16:22:08 +0000 (Thu, 11 Aug 2011) $
8
9.. contents:: Table of Contents
10    :depth: 2
11    :backlinks: top
12
13Background
14----------
15
16The current structure of the ZOO Project documentation process is for
17developers with :ref:`SVN <svn>` commit access to maintain their documents
18in reStructuredText format, and therefore all documents live in the
19/docs directory in SVN.  The `Sphinx <http://sphinx.pocoo.org/>`__ documentation generator is
20used to convert the reStructuredText files to html, and the live
21website is then updated on an hourly basis.
22
23reStructuredText Reference Guides
24---------------------------------
25
26- Docutils `Quick reStructuredText <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`__
27- Docutils `reStructuredText Directives <http://docutils.sourceforge.net/docs/ref/rst/directives.html>`__
28- Sphinx's `reStructuredText Primer <http://sphinx.pocoo.org/rest.html>`__
29- search Sphinx's `mailing list <http://groups.google.com/group/sphinx-dev>`__
30
31reStructuredText Formatting
32---------------------------
33
34- All text should be hard breaks at or around the 80 column mark, just as
35  the source code.
36
37Installing and Using Sphinx for rst-html Generation
38---------------------------------------------------
39
40.. note::
41   
42    You can browse the versions of the Sphinx packages `here <http://pypi.python.org/pypi?%3Aaction=index>`__,
43    and then install the exact version such as:
44       
45    ::
46       
47        easy_install Sphinx==1.0.7
48
49
50**On Windows:**
51
52#. install `Python 2.X <http://www.python.org/>`__
53#. download `setuptools <http://pypi.python.org/pypi/setuptools#windows>`__
54#. make sure that the ``C:/Python2X/Scripts`` directory is your path
55#. execute the following at commandline:
56
57   ::
58
59       easy_install Sphinx
60
61   ...you should see message: "Finished processing dependencies for Sphinx"
62
63   .. note::
64   
65      Make sure you install Sphinx 1.0 or more recent.  See note above.
66     
67#. install `MiKTeX <http://miktex.org>`__ if you want to build pdfs
68     
69#. checkout the /docs directory from SVN, such as:
70
71   ::
72 
73       svn checkout http://svn.zoo-project.org/svn/trunk zoo-project
74     
75#. inside the /docs directory, execute:
76
77   ::
78
79       make html
80
81   or
82
83   ::
84
85       make latex
86
87   the HTML output will be written to the _build/html sub-directory.
88
89**On Linux:**
90
91#. make sure you have the Python dev and setuptools packages installed.
92   On Ubuntu:
93
94   ::
95
96       sudo apt-get install python-dev
97       sudo apt-get install python-setuptools
98
99#. install sphinx using easy_install:
100
101   ::
102
103       sudo easy_install Sphinx
104       
105   .. note::
106   
107      Make sure you install Sphinx 1.0 or more recent.  See note above. 
108     
109#. checkout the /docs directory from SVN, such as:
110
111   ::
112 
113       svn checkout http://svn.zoo-project.org/svn/trunk zoo-project     
114
115#. to process the docs, from the ZOO /docs directory, run:
116
117   ::
118
119       make html
120
121   or
122
123   ::
124
125       make latex
126
127   the HTML output will be written to the build/html sub-directory.
128
129.. note::
130
131    If there are more than one translation, the above commands will automatically
132    build all translations.
133
134
135**On Mac OS X:**
136
137#. install sphinx using easy_install:
138
139   ::
140
141       sudo easy_install Sphinx
142       
143   .. note::
144   
145      Make sure you install Sphinx 1.0 or more recent.  See note above.       
146
147#. install `MacTex <http://www.tug.org/mactex/2009/>`__ if you want to build pdfs
148
149#. checkout the /docs directory from SVN, such as:
150
151   ::
152 
153       svn checkout http://svn.zoo-project.org/svn/trunk zoo-project
154
155#. to process the docs, from the ZOO /docs directory, run:
156
157   ::
158
159       make html
160
161   or
162
163   ::
164
165       make latex
166
167   the HTML output will be written to the build/html sub-directory.
Note: See TracBrowser for help on using the repository browser.

Search

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