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.

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.