Updates to documentation
[spigot:spigot.git] / doc / spigot.html
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
3                "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
4 <html xmlns="http://www.w3.org/1999/xhtml"
5 lang="en" xml:lang="en">
6 <head>
7 <title>Spigot: Rate-limited feed aggregation to StatusNet</title>
8 <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"/>
9 <meta name="generator" content="Org-mode"/>
10 <meta name="generated" content="2012-10-29 21:57:22 PDT"/>
11 <meta name="author" content="Nathan Smith"/>
12 <meta name="description" content=""/>
13 <meta name="keywords" content=""/>
14 <style type="text/css">
15  <!--/*--><![CDATA[/*><!--*/
16   html { font-family: Times, serif; font-size: 12pt; }
17   .title  { text-align: center; }
18   .todo   { color: red; }
19   .done   { color: green; }
20   .tag    { background-color: #add8e6; font-weight:normal }
21   .target { }
22   .timestamp { color: #bebebe; }
23   .timestamp-kwd { color: #5f9ea0; }
24   p.verse { margin-left: 3% }
25   pre {
26         border: 1pt solid #AEBDCC;
27         background-color: #F3F5F7;
28         padding: 5pt;
29         font-family: courier, monospace;
30         font-size: 90%;
31         overflow:auto;
32   }
33   table { border-collapse: collapse; }
34   td, th { vertical-align: top; }
35   dt { font-weight: bold; }
36   div.figure { padding: 0.5em; }
37   div.figure p { text-align: center; }
38   .linenr { font-size:smaller }
39   .code-highlighted {background-color:#ffff00;}
40   .org-info-js_info-navigation { border-style:none; }
41   #org-info-js_console-label { font-size:10px; font-weight:bold;
42                                white-space:nowrap; }
43   .org-info-js_search-highlight {background-color:#ffff00; color:#000000;
44                                  font-weight:bold; }
45   /*]]>*/-->
46 </style>
47 <script type="text/javascript">
48 <!--/*--><![CDATA[/*><!--*/
49  function CodeHighlightOn(elem, id)
50  {
51    var target = document.getElementById(id);
52    if(null != target) {
53      elem.cacheClassElem = elem.className;
54      elem.cacheClassTarget = target.className;
55      target.className = "code-highlighted";
56      elem.className   = "code-highlighted";
57    }
58  }
59  function CodeHighlightOff(elem, id)
60  {
61    var target = document.getElementById(id);
62    if(elem.cacheClassElem)
63      elem.className = elem.cacheClassElem;
64    if(elem.cacheClassTarget)
65      target.className = elem.cacheClassTarget;
66  }
67 /*]]>*///-->
68 </script>
69 </head>
70 <body>
71 <div id="content">
72
73 <h1 class="title">Spigot: Rate-limited feed aggregation to StatusNet</h1>
74
75 <p>Spigot takes syndicated content feeds and posts them to StatusNet accounts at a limited rate. This way you can syndicate content to a StatusNet account without worrying about flooding the account when updates to the feed are frequent.
76 </p>
77 <p>
78 First you set up connections to one or more StatusNet accounts using OAuth or basic authentication. Then you add RSS or Atom feeds, specifying which account to post to, the maximum post frequency, and the format of the posted message. Each time spigot runs, it checks the feeds for new posts, and determines whether or not a new item should be posted based on the specified interval. Spigot can be run in a cron job (or manually) to make regular posts.
79 </p>
80 <p>
81 Spigot is inspired by <a href="https://github.com/zcopley/tricklepost">Tricklepost</a> and <a href="http://brdcst.it/">Brdcst.it</a>.
82 </p>
83 <div id="table-of-contents">
84 <h2>Table of Contents</h2>
85 <div id="text-table-of-contents">
86 <ul>
87 <li><a href="#sec-1">1 Requirements </a></li>
88 <li><a href="#sec-2">2 Download </a></li>
89 <li><a href="#sec-3">3 Installation </a></li>
90 <li><a href="#sec-4">4 Running </a></li>
91 <li><a href="#sec-5">5 Credits </a></li>
92 <li><a href="#sec-6">6 License </a></li>
93 <li><a href="#sec-7">7 FAQ </a></li>
94 </ul>
95 </div>
96 </div>
97
98 <div id="outline-container-1" class="outline-3">
99 <h3 id="sec-1"><span class="section-number-3">1</span> Requirements </h3>
100 <div class="outline-text-3" id="text-1">
101
102 <ul>
103 <li id="sec-1.1">&gt;= Python 2.6 <br/>
104 </li>
105 <li id="sec-1.2">&gt;= <a href="http://pypi.python.org/pypi/argparse/1.2.1">Argparse</a> 1.2.1 (bundled with Python 2.7 or higher) <br/>
106 </li>
107 <li id="sec-1.3">&gt;= <a href="http://pypi.python.org/pypi/feedparser/5.1.2">Feedparser</a> 5.2.1 <br/>
108 </li>
109 <li id="sec-1.4">&gt;= <a href="http://pypi.python.org/pypi/oauth/1.0.1">OAuth</a> 1.0 <br/>
110 </li>
111 </ul>
112 </div>
113
114 </div>
115
116 <div id="outline-container-2" class="outline-3">
117 <h3 id="sec-2"><span class="section-number-3">2</span> Download </h3>
118 <div class="outline-text-3" id="text-2">
119
120 <p>You can obtain spigot in one of two ways:
121 </p><ul>
122 <li id="sec-2.1">Clone the <a href="https://gitorious.org/spigot">git repo</a> <br/>
123 </li>
124 <li id="sec-2.2">Download and extract a <a href="https://gitorious.org/spigot/spigot/archive-tarball/master">tarball</a> <br/>
125 </li>
126 </ul>
127 </div>
128
129 </div>
130
131 <div id="outline-container-3" class="outline-3">
132 <h3 id="sec-3"><span class="section-number-3">3</span> Installation </h3>
133 <div class="outline-text-3" id="text-3">
134
135 <p>Spigot runs from its own working directory. If you have pip, you can install the requirements using <code>pip install -r requirements.txt</code>.
136 </p></div>
137
138 </div>
139
140 <div id="outline-container-4" class="outline-3">
141 <h3 id="sec-4"><span class="section-number-3">4</span> Running </h3>
142 <div class="outline-text-3" id="text-4">
143
144 <p>The first time you run Spigot, it will prompt you to add at least one account and one feed. For further options, pleas run <code>python spigot.py -h</code>.
145 </p></div>
146
147 </div>
148
149 <div id="outline-container-5" class="outline-3">
150 <h3 id="sec-5"><span class="section-number-3">5</span> Credits </h3>
151 <div class="outline-text-3" id="text-5">
152
153 <p>Spigot is (c) 2011-2012 by <a href="mailto:nathan@smithfam.info">Nathan Smith</a>. The statusnet module and portions of Spigot are based off of <a href="http://identicurse.net/">Identicurse</a>.
154 </p></div>
155
156 </div>
157
158 <div id="outline-container-6" class="outline-3">
159 <h3 id="sec-6"><span class="section-number-3">6</span> License </h3>
160 <div class="outline-text-3" id="text-6">
161
162 <p>Spigot is distributed under the terms of the <a href="http://www.gnu.org/licenses/gpl.html">GNU GPL version 3</a> or later.
163 </p></div>
164
165 </div>
166
167 <div id="outline-container-7" class="outline-3">
168 <h3 id="sec-7"><span class="section-number-3">7</span> FAQ </h3>
169 <div class="outline-text-3" id="text-7">
170
171 <ul>
172 <li id="sec-7.1"><b>Where does Spigot store its configuration files and database?</b> <br/>
173 Spigot stores its configuration (spigot.json) and database (spigot.db) in the working directory from which it is invoked. If you are running Spigot from a cron job, you'll want to first cd into the directory containing these.
174
175 </li>
176 <li id="sec-7.2"><b>How often should I run Spigot?</b> <br/>
177 There are a couple factors which weigh on this. First, you want to run it often enough so that catches all of the posts in the feeds it is polling. For example, if you are polling a feed which lists 10 items and is updated about 5 times per hour, you need to run Spigot at least every 2 hours to catch all of those posts in its database.
178
179 <p>
180 Second, you'll want to run Spigot more often than the shortest interval in your configuration. If you run spigot less often than the shortest interval, posts will effectively happen only as often as Spigot runs.
181 </p>
182 <p>
183 In brief, Spigot should run more often than you want to actually post.
184 </p></li>
185 </ul>
186 </div>
187 </div>
188 <div id="postamble">
189 <p class="date"> Date: 2012-10-29 21:57:22 PDT</p>
190 <p class="creator">HTML generated by org-mode 6.33x in emacs 23</p>
191 </div>
192 </div>
193 </body>
194 </html>