| 1 | <html> |
|---|
| 2 | <head> |
|---|
| 3 | <title>PyCommunity documentation center</title> |
|---|
| 4 | <style type="text/css" media="all"> |
|---|
| 5 | @import "./pycommunity.css"; |
|---|
| 6 | </style> |
|---|
| 7 | <script language="javascript" type="text/javascript" |
|---|
| 8 | src="./pycommunity.js" ></script> |
|---|
| 9 | </head> |
|---|
| 10 | <body> |
|---|
| 11 | <div class="backlink"> |
|---|
| 12 | <a href="glossary.html"> |
|---|
| 13 | <img src="media/glossary.png"/> |
|---|
| 14 | Glossary |
|---|
| 15 | </a> |
|---|
| 16 | <a href="tutorials.html"> |
|---|
| 17 | <img src="media/tutorial.png"/> |
|---|
| 18 | Tutorials |
|---|
| 19 | </a> |
|---|
| 20 | <a href="recipes.html"> |
|---|
| 21 | <img src="media/recipe.png"/> |
|---|
| 22 | Recipes |
|---|
| 23 | </a> |
|---|
| 24 | <a href="packages/index.html"> |
|---|
| 25 | <img src="media/package.png"/> |
|---|
| 26 | Packages |
|---|
| 27 | </a> |
|---|
| 28 | <a href="index.html" class="selected"> |
|---|
| 29 | <img src="media/home.png"/> |
|---|
| 30 | Main page |
|---|
| 31 | </a> |
|---|
| 32 | |
|---|
| 33 | </div> |
|---|
| 34 | |
|---|
| 35 | <div class="content"> |
|---|
| 36 | <div class="document" id="pycommunity"> |
|---|
| 37 | <h1 class="title">PyCommunity</h1> |
|---|
| 38 | <p><cite>PyCommunity</cite> is a script that generates a static html website by browsing |
|---|
| 39 | a subversion repository, looking for reSTructuredText documents.</p> |
|---|
| 40 | <p>The idea is to provide a way to automate a project website update everytime |
|---|
| 41 | developers change the documents founded throughout the subversion tree.</p> |
|---|
| 42 | <div class="section"> |
|---|
| 43 | <h1><a id="subversion-layout" name="subversion-layout">Subversion Layout</a></h1> |
|---|
| 44 | <p>To work, <cite>PyCommunity</cite> browses :</p> |
|---|
| 45 | <ul class="simple"> |
|---|
| 46 | <li>a list of packages and extract their documents.</li> |
|---|
| 47 | <li>a directory that holds recipes, to build a cookbook</li> |
|---|
| 48 | <li>a directory that holds tutorials</li> |
|---|
| 49 | <li>a file that contains a glossary</li> |
|---|
| 50 | <li>a file, that is the main README</li> |
|---|
| 51 | <li>a file that is used as the content of the package list page</li> |
|---|
| 52 | </ul> |
|---|
| 53 | <p>A typical layout would be:</p> |
|---|
| 54 | <pre class="literal-block"> |
|---|
| 55 | project |
|---|
| 56 | | |
|---|
| 57 | | |
|---|
| 58 | |-- src |
|---|
| 59 | | | |
|---|
| 60 | | |-- package1 |
|---|
| 61 | | | |
|---|
| 62 | | | |
|---|
| 63 | | module1.py |
|---|
| 64 | | |
|---|
| 65 | |-- doc |
|---|
| 66 | | | |
|---|
| 67 | | |--- packages.txt |
|---|
| 68 | | | |
|---|
| 69 | | |-- README.txt |
|---|
| 70 | | | |
|---|
| 71 | | |--- glossary.txt |
|---|
| 72 | | | |
|---|
| 73 | | |--- recipes |
|---|
| 74 | | | | |
|---|
| 75 | | | |-- recipe1.txt |
|---|
| 76 | | | |
|---|
| 77 | | |--- tutorials |
|---|
| 78 | | | | |
|---|
| 79 | | | |-- tutorial1.txt |
|---|
| 80 | </pre> |
|---|
| 81 | <div class="section"> |
|---|
| 82 | <h2><a id="packages-txt" name="packages-txt">packages.txt</a></h2> |
|---|
| 83 | <p>This file is used as a introduction text in the packages index page.</p> |
|---|
| 84 | </div> |
|---|
| 85 | <div class="section"> |
|---|
| 86 | <h2><a id="readme-txt" name="readme-txt">README.txt</a></h2> |
|---|
| 87 | <p>Used in the main page</p> |
|---|
| 88 | </div> |
|---|
| 89 | <div class="section"> |
|---|
| 90 | <h2><a id="the-glossary-file" name="the-glossary-file">The glossary file</a></h2> |
|---|
| 91 | <p>The glossary file contains all project common words. The idea |
|---|
| 92 | is to collect all words and unify terms, in order to avoid |
|---|
| 93 | speaking about the same thing, using two different words.</p> |
|---|
| 94 | <p>The glossary is a text file. Each line is composed of a word |
|---|
| 95 | a <cite>:</cite> character, and a short definition:</p> |
|---|
| 96 | <pre class="literal-block"> |
|---|
| 97 | glossary: A file that contains definitions |
|---|
| 98 | doctest: A document with runnable examples |
|---|
| 99 | </pre> |
|---|
| 100 | </div> |
|---|
| 101 | <div class="section"> |
|---|
| 102 | <h2><a id="the-recipe-folder" name="the-recipe-folder">The recipe folder</a></h2> |
|---|
| 103 | <p>The recipe folder contains reSTructuredText files. They can |
|---|
| 104 | use an extended tag to mark words that are in the glossary:</p> |
|---|
| 105 | <pre class="literal-block"> |
|---|
| 106 | My super restfile |
|---|
| 107 | ----------------- |
|---|
| 108 | |
|---|
| 109 | is about {{doctest}} |
|---|
| 110 | </pre> |
|---|
| 111 | <p>This allows PyCommunity to generate links and hints in the tutorials |
|---|
| 112 | when it founds such tags.</p> |
|---|
| 113 | <p>The filename without it suffix, is the id of the recipe.</p> |
|---|
| 114 | </div> |
|---|
| 115 | <div class="section"> |
|---|
| 116 | <h2><a id="the-tutorial-folder" name="the-tutorial-folder">The Tutorial folder</a></h2> |
|---|
| 117 | <p>The tutorial folder contains reSTructuredText files. They can |
|---|
| 118 | use an extended tag to mark words that are in the glossary, like |
|---|
| 119 | recipes.</p> |
|---|
| 120 | <p>It can also link to a recipe, by using a recipe prefix and a tag |
|---|
| 121 | like glossary:</p> |
|---|
| 122 | <pre class="literal-block"> |
|---|
| 123 | look at {{recipe:recipe_1}} for details |
|---|
| 124 | </pre> |
|---|
| 125 | <p><cite>PyCommunity</cite> will replace it with the recipe title and a link to the |
|---|
| 126 | recipe.</p> |
|---|
| 127 | <p>The filename without it suffix, is the id of the tutorial.</p> |
|---|
| 128 | </div> |
|---|
| 129 | <div class="section"> |
|---|
| 130 | <h2><a id="the-code-packages" name="the-code-packages">The code packages</a></h2> |
|---|
| 131 | <p><cite>PyCommunity</cite> lists all packages, and scans each one of them, to look |
|---|
| 132 | for all files with the <cite>.txt</cite> extension. <cite>README.txt</cite> is mandatory. |
|---|
| 133 | The files can also use glossary, recipe and tutorial tags:</p> |
|---|
| 134 | <pre class="literal-block"> |
|---|
| 135 | look at {{tutorial:tutorial_1}} for details |
|---|
| 136 | </pre> |
|---|
| 137 | </div> |
|---|
| 138 | </div> |
|---|
| 139 | <div class="section"> |
|---|
| 140 | <h1><a id="website-layout" name="website-layout">Website Layout</a></h1> |
|---|
| 141 | <p><cite>PyCommunity</cite> generates a web structure that looks like this:</p> |
|---|
| 142 | <pre class="literal-block"> |
|---|
| 143 | index.html == main README |
|---|
| 144 | glossary.html |
|---|
| 145 | packages |
|---|
| 146 | index.html (packages list + package.txt content) |
|---|
| 147 | package1 |
|---|
| 148 | index.html (==README.txt) |
|---|
| 149 | epydoc (epydoc) |
|---|
| 150 | module1.html |
|---|
| 151 | tutorials.html (tutorials list) |
|---|
| 152 | tutorials |
|---|
| 153 | tutorial1.html |
|---|
| 154 | cookbook.html (recipe lists) |
|---|
| 155 | cookbook |
|---|
| 156 | recipe1.html |
|---|
| 157 | </pre> |
|---|
| 158 | </div> |
|---|
| 159 | <div class="section"> |
|---|
| 160 | <h1><a id="configuration" name="configuration">Configuration</a></h1> |
|---|
| 161 | <p><cite>PyCommunity</cite> uses <cite>pycommunity.conf</cite> file to know where to get |
|---|
| 162 | its data. Each type of document described in the previous section |
|---|
| 163 | can be located in several places. Target is the folder |
|---|
| 164 | where the website will be generated.</p> |
|---|
| 165 | <p>Example:</p> |
|---|
| 166 | <pre class="literal-block"> |
|---|
| 167 | [packages] |
|---|
| 168 | Package1 = /home/repository/project/src/package1 |
|---|
| 169 | Package2 = /home/repository/project/src/package2 |
|---|
| 170 | |
|---|
| 171 | [templates] |
|---|
| 172 | index=templates/index.pt |
|---|
| 173 | tutorial=templates/tutorial.pt |
|---|
| 174 | recipe=templates/recipe.pt |
|---|
| 175 | glossary=templates/glossary.pt |
|---|
| 176 | recipelist=templates/recipelist.pt |
|---|
| 177 | tutoriallist=templates/tutoriallist.pt |
|---|
| 178 | packageindex=templates/packageindex.pt |
|---|
| 179 | packagedoc=templates/packagedoc.pt |
|---|
| 180 | packagestats=templates/packagestats.pt |
|---|
| 181 | packagesindex=templates/packagesindex.pt |
|---|
| 182 | css=templates/pycommunity.css |
|---|
| 183 | |
|---|
| 184 | [options] |
|---|
| 185 | projectname=PyCommunity |
|---|
| 186 | media=templates/media |
|---|
| 187 | glossary=/home/repository/project/doc/glossary.txt |
|---|
| 188 | index=/home/repository/project/doc/README.txt |
|---|
| 189 | packages=/home/repository/project/doc/packages.txt |
|---|
| 190 | |
|---|
| 191 | [recipes] |
|---|
| 192 | recipes = /home/repository/project/doc/recipes |
|---|
| 193 | more_recipes = /home/repository/project/doc/recipes2 |
|---|
| 194 | |
|---|
| 195 | [tutorials] |
|---|
| 196 | tutos = /home/repository/project/doc/tutorials |
|---|
| 197 | |
|---|
| 198 | [target] |
|---|
| 199 | target1=/home/www |
|---|
| 200 | </pre> |
|---|
| 201 | </div> |
|---|
| 202 | <div class="section"> |
|---|
| 203 | <h1><a id="usage" name="usage">Usage</a></h1> |
|---|
| 204 | <p><cite>PyCommunity</cite> is launched directly, with an optional parameter |
|---|
| 205 | that points to the configuration file. It tries to find it in the |
|---|
| 206 | current directory if none is provided. A log file is aslo filled, |
|---|
| 207 | describing all tasks ran by the tool.</p> |
|---|
| 208 | </div> |
|---|
| 209 | </div> |
|---|
| 210 | </div> |
|---|
| 211 | |
|---|
| 212 | <div class="backlink"> |
|---|
| 213 | <a href="glossary.html"> |
|---|
| 214 | <img src="media/glossary.png"/> |
|---|
| 215 | Glossary |
|---|
| 216 | </a> |
|---|
| 217 | <a href="tutorials.html"> |
|---|
| 218 | <img src="media/tutorial.png"/> |
|---|
| 219 | Tutorials |
|---|
| 220 | </a> |
|---|
| 221 | <a href="recipes.html"> |
|---|
| 222 | <img src="media/recipe.png"/> |
|---|
| 223 | Recipes |
|---|
| 224 | </a> |
|---|
| 225 | <a href="packages/index.html"> |
|---|
| 226 | <img src="media/package.png"/> |
|---|
| 227 | Packages |
|---|
| 228 | </a> |
|---|
| 229 | <a href="index.html" class="selected"> |
|---|
| 230 | <img src="media/home.png"/> |
|---|
| 231 | Main page |
|---|
| 232 | </a> |
|---|
| 233 | |
|---|
| 234 | </div> |
|---|
| 235 | |
|---|
| 236 | </body> |
|---|
| 237 | </html> |
|---|
