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

Last change on this file since 272 was 272, checked in by nbozon, 13 years ago

add keywords with svn propset

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