tsr/planet
1
0
Fork 0
Code Issues 3 Pull Requests Releases Wiki Activity

Documentation updates

Browse Source
This commit is contained in:
Sam Ruby 2006-10-17 09:57:38 -04:00
parent 6946febede
commit 17aed24966
11 changed files with 119 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README
View File

@ -9,11 +9,11 @@ also actively being maintained.
It uses Mark Pilgrim's Universal Feed Parser to read from CDF, RDF, RSS and
Atom feeds; Leonard Richardson's Beautiful Soup to correct markup issues;
and Tomas Styblo's templating engine to output static files in any
format you can dream up.
and either Tomas Styblo's templating engine Daniel Viellard's implementation
of XSLT to output static files in any format you can dream up.
To get started, check out the INSTALL file in this directory. If you have any
questions or comments, please don't hesitate to use the planet mailing list:
To get started, check out the documentation in the docs directory. If you have
any questions or comments, please don't hesitate to use the planet mailing list:
http://lists.planetplanet.org/mailman/listinfo/devel

5
TODO
View File

@ -1,11 +1,6 @@
TODO
====
* Enable per-feed adjustments
The goal is to better cope with feeds that don't have dates or ids or
consitently encode or escape things incorrectly.
* Expire feed history
The feed cache doesn't currently expire old entries, so could get

51
docs/config.html
View File

@ -27,6 +27,7 @@ either (or both) of <code>template_files</code> and <code>theme</code>.</p>
<p>Below is a complete list of predefined planet configuration parameters,
including <del>ones not (yet) implemented by Venus</del> and <ins>ones that
are either new or implemented differently by Venus</ins>.</p>
<blockquote>
<dl class="compact code">
<dt>name</dt>
@ -37,16 +38,35 @@ are either new or implemented differently by Venus</ins>.</p>
<dd>Your name</dd>
<dt>owner_email</dt>
<dd>Your e-mail address</dd>
</dl>
<dl class="compact">
<dt>cache_directory</dt>
<dd>Where cached feeds are stored</dd>
<dt>log_level</dt>
<dd>One of <code>DEBUG</code>, <code>INFO</code>, <code>WARNING</code>, <code>ERROR</code> or <code>CRITICAL</code></dd>
<dt><ins>output_theme</ins></dt>
<dt>output_dir</dt>
<dd>Directory to place output files</dd>
</dl>
<dl class="compact">
<dt><ins>theme</ins></dt>
<dd>Directory containing a <code>config.ini</code> file which is merged
with this one. This is typically used to specify templating and bill of
material information.</dd>
<dt>output_dir</dt>
<dd>Directory to place output files</dd>
<dt>template_files</dt>
<dd>Space-separated list of output template files</dd>
<dt><ins>template_directories</ins></dt>
<dd>Space-separated list of directories in which <code>template_files</code>
can be found</dd>
<dt><ins>bill_of_materials</ins></dt>
<dd>Space-separated list of files to be copied as is directly from the <code>template_directories</code> to the <code>output_dir</code></dd>
<dt><ins>filters</ins></dt>
<dd>Space-separated list of filters to apply to each entry</dd>
</dl>
<dl class="compact">
<dt>items_per_page</dt>
<dd>How many items to put on each page. <ins>Whereas Planet 2.0 allows this to
be overridden on a per template basis, Venus currently takes the maximum value
@ -61,22 +81,19 @@ for this across all templates.</ins></dd>
<dd>Output encoding for the file, Python 2.3+ users can use the special "xml" value to output ASCII with XML character references</dd>
<dt><del>locale</del></dt>
<dd>Locale to use for (e.g.) strings in dates, default is taken from your system</dd>
<dt>activity_threshold</dt>
<dd>If non-zero, all feeds which have not been updated in the indicated
number of days will be marked as inactive</dd>
</dl>
<dl class="compact">
<dt>log_level</dt>
<dd>One of <code>DEBUG</code>, <code>INFO</code>, <code>WARNING</code>, <code>ERROR</code> or <code>CRITICAL</code></dd>
<dt>feed_timeout</dt>
<dd>Number of seconds to wait for any given feed</dd>
<dt><del>new_feed_items</del></dt>
<dd>Number of items to take from new feeds</dd>
<dt>activity_threshold</dt>
<dd>If non-zero, all feeds which have not been updated in the indicated
number of days will be marked as inactive</dd>
<dt>template_files</dt>
<dd>Space-separated list of output template files</dd>
<dt><ins>template_directories</ins></dt>
<dd>Space-separated list of directories in which <code>template_files</code>
can be found</dd>
<dt><ins>bill_of_materials</ins></dt>
<dd>Space-separated list of files to be copied as is directly from the <code>template_directories</code> to the <code>output_dir</code></dd>
<dt><ins>filters</ins></dt>
<dd>Space-separated list of filters to apply to each entry</dd>
</dl>
</blockquote>

21
docs/docs.css
View File

@ -12,21 +12,18 @@ a:link, a:visited {
color: #333;
text-decoration: none !important;
border-bottom: 1px dotted #333 !important;
text-decoration: underline;
border-bottom: 0;
}
a:hover {
background-color: transparent;
color: #993344;
color: #934;
text-decoration: none !important;
text-decoration: underline;
border-bottom: 1px dotted #993344 !important;
border-bottom: 0;
}
code {
color: green;
background-color: #FFF;
color: #00F;
font-size: large
}
@ -42,14 +39,13 @@ h2 {
clear: both;
}
ul.outer > li {
ul, ul.outer > li {
margin: 14px 0 10px 0;
}
.z {
float:left;
background: url(img/shadowAlpha.png) no-repeat bottom right !important;
background: url(img/shadow.gif) no-repeat bottom right;
margin: -15px 0 20px -15px !important;
}
@ -60,21 +56,18 @@ ul.outer > li {
.z .sectionInner {
width: 730px;
background: none !important;
background: url(img/shadow2.gif) no-repeat left top;
padding: 0 !important;
padding: 0 6px 6px 10;
}
.z .sectionInner .sectionInner2 {
background-color: #fff;
border: 1px solid #a9a9a9;
padding: 4px;
margin: -6px 6px 6px -6px !important;
margin: 0;
}
ins {
color: magenta;
background-color: #FFF;
color: #F0F;
text-decoration: none;
}
@ -84,7 +77,7 @@ dl.compact {
}
dl.code > dt {
font-family: mono;
font-family: monospace;
}
dl.compact > dt {

2
docs/docs.js
View File

@ -1,6 +1,8 @@
window.onload=function() {
var vindex = document.URL.lastIndexOf('venus/');
if (vindex<0) vindex = document.URL.lastIndexOf('planet/');
var base = document.URL.substring(0,vindex+6);
if (vindex<0) vindex = '..';
var body = document.getElementsByTagName('body')[0];
var div = document.createElement('div');

BIN
docs/img/shadow.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 4.3 KiB

BIN
docs/img/shadow2.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 3.9 KiB

3
docs/index.html
View File

@ -10,6 +10,7 @@
<body>
<h2>Table of Contents</h2>
<ul class="outer">
<li><a href="installation.html">Getting started</a></li>
<li>Basic Features
<ul>
<li><a href="config.html">Configuration</a></li>
@ -38,7 +39,7 @@
<li><a href="http://www.gnu.org/software/sed/manual/html_mono/sed.html">sed</a></li>
</ul>
</li>
<li>Legal
<li>Credits and License
<ul>
<li><a href="../AUTHORS">Authors</a></li>
<li><a href="../THANKS">Contributors</a></li>

66
docs/installation.html Normal file
View File

@ -0,0 +1,66 @@
<!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN"
"http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<script type="text/javascript" src="docs.js"></script>
<link rel="stylesheet" type="text/css" href="docs.css"/>
<title>Venus Installation</title>
</head>
<body>
<h2>Installation</h2>
<p>Venus has been tested on Linux, and Mac OSX, and Windows.</p>
<p>You'll need at least Python 2.2 installed on your system, we recommend
Python 2.4 though as there may be bugs with the earlier libraries.</p>
<p>Everything Pythonesque Planet need to provide basic operation should be
included in the distribution. Additionally:</p>
<ul>
<li>Usage of XSLT requires either
<a href="http://xmlsoft.org/XSLT/xsltproc2.html">xsltproc</a>
or <a href="http://xmlsoft.org/XSLT/python.html">python-libxslt</a>.</li>
<li>The current interface to filters written in non-templating languages
(e.g., python) uses the
<a href="http://docs.python.org/lib/module-subprocess.html">subprocess</a>
module which was introduced in Python 2.4.</li>
<li>Usage of FOAF as a reading list requires
<a href="http://librdf.org/">librdf</a>.</li>
</ul>
<h3>Instructions</h3>
<ol>
<li><p>If you are reading this online, you will need to
<a href="..">download</a> and extract the files into a folder somewhere.
You can place this wherever you like, <code>~/planet</code>
and <code>~/venus</code> are good
choices, but so's anywhere else you prefer.</p></li>
<li><p>This is very important: from within that directory, type the following
command:</p>
<blockquote><code>python runtests.py</code></blockquote>
<p>This should take anywhere from a one to ten seconds to execute. No network
connection is required, and the script cleans up after itself. If the
script completes with an "OK", you are good to go. Otherwise stopping here
and inquiring on the
<a href="http://lists.planetplanet.org/mailman/listinfo/devel">mailing list</a>
is a good idea as it can save you lots of frustration down the road.</p></li>
<li><p>Make a copy of one of the <code>ini</code> the files in the
<a href="../examples">examples</a> subdirectory,
and put it wherever you like; I like to use the Planet's name (so
<code>~/planet/debian</code>), but it's really up to you.</p></li>
<li><p>Edit the <code>config.ini</code> file in this directory to taste,
it's pretty well documented so you shouldn't have any problems here. Pay
particular attention to the <code>output_dir</code> option, which should be
readable by your web server. If the directory you specify in your
<code>cache_dir</code> exists; make sure that it is empty.</p></li>
<li><p>Run it: <code>python planet.py pathto/config.ini</code></p>
<p>You'll want to add this to cron, make sure you run it from the
right directory.</p></li>
<li><p>(Optional)</p>
<p>Tell us about it! We'd love to link to you on planetplanet.org :-)</p></li>
<li><p>(Optional)</p>
<p>Build your own themes, templates, or filters! And share!</p></li>
</ol>
</body>
</html>

5
docs/normalization.html
View File

@ -51,12 +51,13 @@ in other areas in the feed too.</p>
<a href="http://www.crummy.com/software/BeautifulSoup/documentation.html#Parsing%20HTML">knowledge of the semantics of HTML</a>. Additionally, a
<a href="http://golem.ph.utexas.edu/~distler/blog/archives/000165.html#sanitizespec">large
subset of MathML</a>, as well as a
<a href="http://www.w3.org/TR/SVGMobile/">tiny profile of SVG is also supported.</a></p>
<a href="http://www.w3.org/TR/SVGMobile/">tiny profile of SVG</a>
is also supported.</p>
<h3>Atom 1.0</h3>
<p>The Universal Feed Parser also
<a href="http://www.feedparser.org/docs/content-normalization.html">normalizes the content of feeds</a>. This involves a
<a href="http://www.feedparser.org/docs/reference.html">large number of elements</a>; the best place to start is to look at
<a href="http://www.feedparser.org/docs/annotated-examples.html">annotated examples</a>. Among other things a large number of
<a href="http://www.feedparser.org/docs/annotated-examples.html">annotated examples</a>. Among other things a wide variety of
<a href="http://www.feedparser.org/docs/date-parsing.html">date formats</a>
are converted into
<a href="http://www.ietf.org/rfc/rfc3339.txt">RFC 3339</a> formatted dates.</p>

2
themes/asf/index.html.xslt
View File

@ -153,7 +153,7 @@
<img src="{atom:source/atom:icon}" class="icon"/>
</xsl:if>
<a href="{atom:source/atom:link[@rel='alternate']/@href}">
<xsl:attribute name="title" select="{atom:source/atom:title}"/>
<xsl:attribute name="title" select="atom:source/atom:title"/>
<xsl:value-of select="atom:source/planet:name"/>
</a>
<xsl:if test="string-length(atom:title) &gt; 0">