Title: Website Development
Notice:    Licensed to the Apache Software Foundation (ASF) under one
           or more contributor license agreements.  See the NOTICE file
           distributed with this work for additional information
           regarding copyright ownership.  The ASF licenses this file
           to you under the Apache License, Version 2.0 (the
           "License"); you may not use this file except in compliance
           with the License.  You may obtain a copy of the License at
           .
             http://www.apache.org/licenses/LICENSE-2.0
           .
           Unless required by applicable law or agreed to in writing,
           software distributed under the License is distributed on an
           "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
           KIND, either express or implied.  See the License for the
           specific language governing permissions and limitations
           under the License.

We use [Apache Subversion][1] for version control. You can [browse our 
repository][2] in your web browser.

Quick editing of the site is available for committers using the Apache CMS
[from your browser.][6]

This page gives instructions on doing website development on your local computer.

* [Setup](#setup) - How to download the Odf project site repos and setup the Apache CMS.
* [Directory Layout](#directory-layout) - Where to find the content, templates, and scripts.
* [Local Development](#local-development) - How to build and test locally.
* [Submitting Your Results](#submitting-your-results) - How to contribute your edits.

## Setup

### Create a directory on your computer.

    mkdir odf-site
    cd odf-site

### Download the svn repos for the Odf site.

    svn co https://svn.apache.org/repos/asf/incubator/odf/site/trunk site

### Download the svn repos for the Apache CMS.

    svn co https://svn.apache.org/repos/infra/websites/cms/ cms


### Install Python dependencies.

Adapted from the [Apache CMS Reference][3]

The easiest way to install the dependencies is to use Python setuptools.

#### Check your version of Python

    python --version

#### Follow the installation instructions for [setuptools][4].

#### Install dependencies

    sudo easy_install Pygments
    sudo easy_install ElementTree
    sudo easy_install Markdown

## Directory Layout

#### Content directory

The `site/content/odftoolkit` directory contains web content - markdown, html, javascript, css, images and other files. Files that do not fit recognized patterns from `site/lib/path.pm` are copied as is to the web site during the build.

#### Templates directory

The `site/templates` directory contains the html skeletons used during the site build.

* `skeleton.html` - our current html page template.
* `sidenav.mdtext` - markdown of the side navigation panel.

#### Lib directory

The `site/lib` directory contains two python modules that determine how content files are processed during the site build.

* `path.pm` - maps file patterns like `.mdtext` into the view building routines. We can expand to cover other patterns.
* `view.pm` - a set of python subroutines for converting content into web pages.

#### Build tools

You can find the CMS build tools in the `cms` directory.

* `cms/build/` - perl scripts for building the site and markdown extensions.
* `cms/conversion-utilities/` - scripts used by various projects for conversion including `cwiki` conversion.
* `cms/webgui/` - the webgui behind the `bookmarklet`.

These can be extended locally. Before any changes become part of our process they will need to be cleared with Apache Infrastructure. We'll need to submit patches. These should be additive or be bug fixes.

## Local Development

### Edit the site

Using your favorite editors edit the site content, templates, and lib scripts.

### Python Markdown Daemon

Start the Python Markdown daemon.

    export MARKDOWN_SOCKET=`pwd`/markdown.socket PYTHONPATH=`pwd`
    python cms/build/markdownd.py

### Build the site.

    cms/build/build_site.pl --source-base site --target-base www

### Copy the site to your computer's web server.

On my Mac:

    sudo scp -rp www/content/odftoolkit /Library/WebServer/Documents/.

The site is then available with [http://localhost/odftoolkit/][5].

Or serve the site directly using the Python SimpleHTTPServer:

    (cd www/content/ && python -m SimpleHTTPServer 8080)

The site is then available with [http://localhost:8080/odftoolkit/][8].

## Submitting your results.

### Committer

Do the appropriate combination of svn status, svn add, and svn commits. Commits will cause staging rebuilds.
See [How to Edit the ODF Toolkit Website][6]

### Contributor

(Add instructions on creating patches.)

For further information see the [Apache Source Code Repository][7] page.

[1]: http://subversion.apache.org
[2]: http://svn.apache.org/viewvc/incubator/odf/site/trunk
[3]: http://www.apache.org/dev/cmsref.html#local-build
[4]: http://pypi.python.org/pypi/setuptools
[5]: http://localhost/odftoolkit
[6]: docs/edit-cms.html
[7]: http://www.apache.org/dev/version-control.html
[8]: http://localhost:8080/odftoolkit/