Skip to content

Commit 023f475

Browse files
aparrishaparrish
committed
updated README with some helpful tips and basics
1 parent 20d9094 commit 023f475

1 file changed

Lines changed: 151 additions & 17 deletions

File tree

‎README.md‎

Lines changed: 151 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,154 @@
1-
# Processing Py Site [![How are we doing?](https://travis-ci.org/kazimuth/processing-py-site.svg)](https://travis-ci.org/kazimuth/processing-py-site)
1+
# Processing.py Documentation [![How are we doing?](https://travis-ci.org/kazimuth/processing-py-site.svg)](https://travis-ci.org/kazimuth/processing-py-site)
22

3-
Repository for py.processing.org.
3+
This repository contains the files and executable code used to build
4+
[py.processing.org](http://py.processing.org), the official documentation for
5+
[Processing.py](https://github.com/jdf/processing.py).
6+
7+
## Dependencies and installation
8+
9+
To build this project, you need to have the following software installed:
10+
11+
* Java (1.8+)
12+
* Python (2.7+, untested with Python 3)
13+
14+
(Both `java` and `python` should be in your path.)
15+
16+
You'll need to install the various Python library requirements as well. These
17+
requirements are provided in this repository in the standard `pip`-formatted
18+
`requirements.txt`. The
19+
easiest way to do this is to [create and activate a Python virtual
20+
environment](http://docs.python-guide.org/en/latest/dev/virtualenvs/) and then
21+
install the requirements with `pip` like so:
22+
23+
pip install -r requirements.txt
24+
25+
(Tip: For most platforms, it's easier to install `lxml` if you upgrade `pip`
26+
first. With your virtual environment activated, type `pip install -U pip` and
27+
then install the packages with the command above.)
28+
29+
Finally, you'll need the standalone Processing.py JAR file. You can build
30+
Processing.py from source to obtain this file, or download the pre-built JAR
31+
for your platform using the appropriate link below:
32+
33+
* [Mac OS X](http://py.processing.org/processing.py-macosx.tgz)
34+
* Windows: [64-bit](http://py.processing.org/processing.py-windows64.zip),
35+
[32-bit](http://py.processing.org/processing.py-windows32.zip)
36+
* Linux: [64-bit](http://py.processing.org/processing.py-linux64.tgz)
37+
[32-bit](http://py.processing.org/processing.py-linux32.tgz)
38+
39+
Unarchive the file you downloaded and copy the two files with a `.jar`
40+
extension into your `processing-py-site` directory.
41+
42+
## Overview
43+
44+
The `generator.py` script takes the various files in this repository, processes
45+
them and generates a static HTML site. (You can think of `generator.py` as
46+
being a kind of bespoke static site generator, akin to, e.g.,
47+
[Jekyll](https://jekyllrb.com/).) Running the following command will build the
48+
entire site:
49+
50+
python generator.py build --all --images
51+
52+
(See below for further discussion of the command line options available
53+
in `generator.py`.) The best way to understand how the site is generated is to
54+
study `generator.py`'s source code, but here's the basic overview.
55+
56+
* The `Reference/api_en` directory contains a number of XML files. These files
57+
are used to generate the "Reference" section of the documentation, including
58+
the images, which are automatically generated from the `<code>` blocks in the
59+
XML files. (The order of sections in the Reference index is hard-coded in
60+
`generator.py`.)
61+
* The `Tutorials` directory has a number of subdirectories, each containing a
62+
tutorial that appears on in the "Tutorials" section. The tutorials themselves
63+
are written in plain HTML. The Tutorials index page is generated using the
64+
`tutorials.xml` file to determine the order, and using the `tutorial.xml`
65+
file in each subdirectory to determine metadata.
66+
* The `content` directory contains static files used in the site layout, such
67+
as stylesheets and images. The contents of this directory are simply copied
68+
verbatim to the generated site.
69+
* The `templates` directory contains a number of HTML templates, written in the
70+
[Jinja](http://jinja.pocoo.org/docs/dev/) templating language. These are
71+
mostly used to produce the various index pages for the reference and
72+
tutorials. The XML source code for each reference item is rendered by the
73+
`reference_item_template.jinja` template; there's a (fairly) straightforward
74+
correspondence between the name of the XML tag and the variable used to
75+
reference the tag in the template.
76+
* The `jython` directory contains a single script, `generate_images.py`, which
77+
is used to generate images from the example code in the reference items.
78+
(This program is executed automatically by the build process; there's no
79+
reason for you to run it yourself.)
80+
81+
On successful completion of `generator.py`, the static site ends up in the
82+
`generated` directory.
83+
84+
## Building the documentation
85+
86+
As noted above, the `generator.py` script builds the site from the source
87+
files in the repository. Run `python generator.py --help` for full details on
88+
its command line options. Here's an overview:
489

5-
Install requirements:
6-
```sh
7-
./generator.py bootstrap
8-
```
990
To build all content:
10-
```sh
11-
./generator.py build --all --images
12-
```
13-
To test the site in a local server
14-
```sh
15-
./generator.py test
16-
```
17-
To see what else you can do:
18-
```sh
19-
./generator.py --help
20-
```
91+
92+
python generator.py build --all --images
93+
94+
To build the site without performing the image generation process:
95+
96+
python generator.py build
97+
98+
To build only `a.xml`, `b.xml` and `c.xml` files from the reference (remove
99+
`--images` to skip the image generation process):
100+
101+
python generator.py build --images --files a.xml b.xml c.xml
102+
103+
To test the site in a local server:
104+
105+
python generator.py test
106+
107+
## Troubleshooting
108+
109+
Here are a few common and/or possible scenarios you might run into...
110+
111+
### Error: Could not find or load main class org.python.util.jython
112+
113+
You're missing the Jython code necessary to execute the image generation
114+
script. Ensure that you've copied (or linked) `processing-py.jar` from the
115+
standalone Processing.py distribution into your `processing-py-site` directory.
116+
117+
### NullPointerException - foo is probably dynamic-mode; fix that, please.
118+
119+
The image generation process only creates images for "static-mode" sketches,
120+
i.e., sketches that don't have a `draw()` function and therefore can't be
121+
animated or interactive. To fix this, rewrite the code example so it isn't
122+
interactive, or add `<notest /><noimage />` as children of the `<example>` tag
123+
in the XML to suppress image generation for that item.
124+
125+
### Could not initialize class com.jogamp.newt.NewtFactory
126+
127+
I've seen this error when trying to build on Linux without
128+
`processing-py-natives-linux-amd64.jar` in the `processing-py-site` directory.
129+
Ensure this file (or the file appropriate for your platform) is present and try
130+
again.
131+
132+
### I can't run the image generation process in a headless environment
133+
134+
If you're running on a Linux machine without a connected display (say, an EC2
135+
box), you'll need to install `xvfb` using the package manager for your
136+
operating system. Then run the build script like so:
137+
138+
xvfb-run python generator.py build --images
139+
140+
## Contributing
141+
142+
We welcome contributions! To contribute new documentation or fixes to the
143+
existing documentation, create a fork of the
144+
[processing-py-site](https://github.com/kazimuth/processing-py-site) repository
145+
on GitHub. With `git`, create a new branch in your fork and make your changes,
146+
ensuring that `python generator.py build --all --images` completes without
147+
errors. When you're done, push your branch to your fork of the project on
148+
Github, and then issue a Pull Request against the main repository. [Here's a
149+
good overview of the pull request
150+
process](https://yangsu.github.io/pull-request-tutorial/) on GitHub. (If you're
151+
totally unfamiliar with Git or GitHub, [try this
152+
tutorial](https://try.github.io/).
153+
154+

0 commit comments

Comments
 (0)