git.guelker.eu uranus / master README
master

Tree @master (Download .tar.gz)

README @masterraw · history · blame

Uranus Ruby Planet Generator
============================

Uranus generates a planet (aka blogroll) from a given set of RSS or
Atom feeds. It was written because the main software used for such
purposes, Planet (see http://www.planetplanet.org) has not seen any
development since years and fails on certain HTTPS URLs. Likewise, any
spinoffs planet caused are not developed anymore either as can
currently be seen impressively on the Debian planet (see
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=813313).

There is another alternative, Pluto, which was written by Gerald Bauer
(see https://github.com/feedreader/pluto). The software however has
basically no documentation, which makes it hard to use, and it has a
large number of dependencies, which seems overengineered for such a
simple purpose as collecting some feeds.

So, here is Uranus. It has exactly no dependencies other than Ruby
with its included standard library, thus it should work on any modern
Ruby installation without further work.

			 --- Installation ---

I don’t currently do releases of Uranus, but cloning the Git
repository is enough to get up and running. Once you installed the
Ruby interpreter (see https://www.ruby-lang.org or just use your
distribution's package manager), do this:

    $ git clone git://git.guelkerdev.de/uranus.git

That’s it. You can continue with the configuration as outlined below.

			--- Configuration ---

Uranus can currently generate exactly one planet per
installation. Most people will probaly not want to host multiple
planets, and even if that is required, one can just install another
copy of Uranus for the new planet. Maybe I extend Uranus later to
support multiple planets.

The main configuration is done in the config.yml file, which is a file
in YAML format, i.e. key-value pairs are separated by colons and you
need to be careful with leading whitespace, as it is significant. Just
edit the example configuration file to suit your needs.

The example configuration file explains all directives
available. Since there are no optional directives, you'll have to edit
them all anyway (or leave them at the default values).

Make sure the directories you configure actually exist. Uranus won't
create them for you and will fail if they are not there. This is
especially relevant if you for whatever reason want it to use a
temporary file system like the hierarchy under /tmp on many Linux
distributions.

			  --- Templates ---

Templates are the part where you will spent most time. When run,
Uranus copies all files inside the configured `template_dir' that do
/not/ end with `.erb' /unmodified/ into the directory configured via the
`output_dir' configuration option. This is useful for stylesheets,
images, and other static content.

All files inside the `template_dir' that /do/ end with `.erb' are
/template files/. These files are processed by Uranus before the
result is stored under the same file name with just `.erb' stripped
inside the `output_dir' directory.

The template files can contain whatever you want; the processor looks
for tags that look like <% ... %> and <%= ... %>, which makes them
look nice in HTML files. Everything between these two tags is executed
as (Ruby) code, though it is not required to know Ruby to modify
template files as the DSL provided makes things pretty simple. If you
do know Ruby, then you can of course make use of the full
possibilities this gives. The <% ... %> form only executes the
contained code, but does not insert anything into the document
written. <%= ... %> inserts the result of the operation at the point
this tag was encountered into the document.

The most important things about the Ruby syntax that you'll need:

1) Conditions:

Conditionals look like this:

    if condition
      # Code if true
    else
      # Code if false
    end

2) For loop:

Iterate over a collection like this:

    for item in collection
      # Do something with `item'
    end

3) Method call:

Use a colon to invoke a method, as in `obj.method'. Parentheses around
method arguments are optional.

The processor makes a number of special variables available to you;
these variables all start with an @ sign, and a reference is
below. See the provided index.html.erb file for an example of using
them. The most important, but also most complex variable is @entries,
which is a nested array of articles. The articles are grouped first by
day, then by feed so that when iterating the list you first get all
feeds that published something on a given day and one level deeper all
articles in that feed. This is particularyly useful when building a
web page, but if you don't need this nice structure, use @flat_entries
instead, which is an ordinary array consisting just of all articles in
descending order.

Both @entries and @flat_entries contain Entry objects, which will give
you information both about the article and the feed the article came
from. See below for the exact methods available.

		      --- Variable reference ---

The following variables are available in a template:

@generator [String]
This is the name and version of Uranus.

@planet_title [String]
The value of the configuration directive `planet_title'.

@planet_link [String]
The value of the configuration directive `planet_link'.

@owner_name [String]
The value of the configuration directive `owner_name'.

@owner_email [String]
The value of the configuration directive `owner_email'.

@entries [Nested array of Entry objects]
A grouped (nested) list of Entry objects. The
number of items on the lowest level of this array taken together is at
maximum the number of items configured via the `item_count' directive
in the configuration file.

@flat_entries [Array of Entry objects]
The same entries as in @entries, but without the nesting.

@feeds [Array of Feed objects]
A list of Feed objects each representing one subscribed feed.

		       --- Helper functions ---

The following helper functions are available:

escape_html( str ) -> String
This function escapes any special HTML characters, such as < or & and
returns the result, which can safely be included into an HTML DOM.

strftime( time, format ) -> String
Takes a Time object and applies a date(1)-like string to it, i.e.
%Y is replaced by the time's year, %d by the day, etc. Refer to
date(1) for the available % sequences.

			    --- Entry ---

Objects of this kind have two methods.

feed() -> Feed
This returns the feed an article is associated with.

article() -> article
This returns the actual article, with all information such as title,
link, and content.

			     --- Feed ---

On these the following methods are available:

url() -> String
The URL to the RSS or Atom feed subscribed to.

title() -> String
The title of the feed, as it was configured in the configuration file
for this feed.

human_url() -> String
The URL to the human-readable website of the feed susbcribed to, as
configured in the configuration file for this feed.

custom_key( key ) -> String
This method takes as argument a string key and returns one of the
additional entries for this feed in the configuration file.

			   --- Article ---

These have the methods url(), title(), author(), summary(), and
content(), which all return strings and are otherwise
self-explanatory. Additionally, date() returns the publishing date
(you can pass this into the strftime() helper).

Beware that author() and summary() may be nil, i.e. nothing. If you
insert nil into the template, nothing will be inserted.