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