root / pycommunity / etc / README.txt

===========
PyCommunity
===========

`PyCommunity` is a script that generates a static html website by browsing
a subversion repository, looking for reSTructuredText documents. 

The idea is to provide a way to automate a project website update everytime 
developers change the documents founded throughout the subversion tree.

Subversion Layout
=================

To work, `PyCommunity` browses : 

- a list of packages and extract their documents.

- a directory that holds recipes, to build a cookbook

- a directory that holds tutorials

- a file that contains a glossary

- a file, that is the main README

- a file that is used as the content of the package list page

A typical layout would be::

    project 
      |
      |
      |-- src
      |    | 
      |    |-- package1
      |           |
      |           |
      |         module1.py     
      |         
      |-- doc
      |    |
      |    |--- packages.txt
      |    |
      |    |--  README.txt
      |    |  
      |    |--- glossary.txt
      |    |
      |    |--- recipes
      |    |       |
      |    |       |-- recipe1.txt
      |    |       
      |    |--- tutorials
      |    |      |
      |    |      |-- tutorial1.txt

packages.txt
------------

This file is used as a introduction text in the packages index page.

README.txt
----------

Used in the main page

The glossary file
-----------------

The glossary file contains all project common words. The idea
is to collect all words and unify terms, in order to avoid 
speaking about the same thing, using two different words.

The glossary is a text file. Each line is composed of a word
a `:` character, and a short definition::

    glossary: A file that contains definitions
    doctest: A document with runnable examples

The recipe folder
-----------------

The recipe folder contains reSTructuredText files. They can
use an extended tag to mark words that are in the glossary::

    My super restfile
    -----------------

    is about {{doctest}}

This allows PyCommunity to generate links and hints in the tutorials
when it founds such tags.

The filename without it suffix, is the id of the recipe.


The Tutorial folder
-------------------

The tutorial folder contains reSTructuredText files. They can
use an extended tag to mark words that are in the glossary, like
recipes.

It can also link to a recipe, by using a recipe prefix and a tag
like glossary::

    look at {{recipe:recipe_1}} for details

`PyCommunity` will replace it with the recipe title and a link to the
recipe.    
 
The filename without it suffix, is the id of the tutorial.

The code packages
-----------------

`PyCommunity` lists all packages, and scans each one of them, to look
for all files with the `.txt` extension. `README.txt` is mandatory.
The files can also use glossary, recipe and tutorial tags::

    look at {{tutorial:tutorial_1}} for details

Website Layout
==============

`PyCommunity` generates a web structure that looks like this::

    index.html == main README
    glossary.html       
    packages
        index.html (packages list + package.txt content)
        package1
            index.html (==README.txt)
            epydoc (epydoc)
            module1.html
    tutorials.html (tutorials list)
    tutorials
        tutorial1.html
    cookbook.html (recipe lists)
    cookbook
        recipe1.html
        
Configuration
=============

`PyCommunity` uses `pycommunity.conf` file to know where to get
its data. Each type of document described in the previous section
can be located in several places. Target is the folder
where the website will be generated.

Example::

    [packages]
    Package1 = /home/repository/project/src/package1
    Package2 = /home/repository/project/src/package2
    
    [templates]
    index=templates/index.pt
    tutorial=templates/tutorial.pt
    recipe=templates/recipe.pt
    glossary=templates/glossary.pt
    recipelist=templates/recipelist.pt
    tutoriallist=templates/tutoriallist.pt
    packageindex=templates/packageindex.pt
    packagedoc=templates/packagedoc.pt
    packagestats=templates/packagestats.pt
    packagesindex=templates/packagesindex.pt
    css=templates/pycommunity.css

    [options]
    projectname=PyCommunity
    media=templates/media
    glossary=/home/repository/project/doc/glossary.txt
    index=/home/repository/project/doc/README.txt
    packages=/home/repository/project/doc/packages.txt

    [recipes]
    recipes = /home/repository/project/doc/recipes
    more_recipes = /home/repository/project/doc/recipes2
 
    [tutorials]
    tutos = /home/repository/project/doc/tutorials

    [target]
    target1=/home/www
 
Usage
=====

`PyCommunity` is launched directly, with an optional parameter
that points to the configuration file. It tries to find it in the
current directory if none is provided. A log file is aslo filled, 
describing all tasks ran by the tool.