Website Development

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

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

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

Setup - How to download the Odf project site repos and setup the Apache CMS.
Directory Layout - Where to find the content, templates, and scripts.
Local Development - How to build and test locally.
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

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

Check your version of Python¶

python --version

Source code generation has been tested successfully with Python 2.7.15rc1

Follow the installation instructions for setuptools.¶

Install dependencies¶

sudo apt-get install -y python2.7-elementtree
sudo apt install python-pip
python -m pip install "Markdown<2.6.0"
python -m pip install "Pygments==2.2.0"

The Apache CMS 3 depends on old libraries. NOTE: The former described 'easy_install' approach is no longer working.

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/.

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/.

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

Contributor¶

(Add instructions on creating patches.)

For further information see the Apache Source Code Repository page.

General¶

Components¶

Community¶

Development¶

TDF¶