Mercurial > silorider

annotate README.rst @ 33:9e4eb3f2754e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Improve handling of character limits in html stripping The code now more closely keeps track of character counts during html stripping, and should be absolutely exact. When the limit is exceeded, it now restarts the stripping without any URLs to prevent incorrect trimming. It also better preserves whitespace in the original post. New tests are added for Twitter silo to ensure it works as expected.
author Ludovic Chabant <ludovic@chabant.com>
date Wed, 10 May 2023 16:10:12 -0700
parents 678278cb85b1
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
1
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
2 SiloRider
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
3 =========
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
4
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
5 SiloRider is a command-line utility that lets you implement the `POSSE`_ model
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
6 on a website. This is how it works:
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
7
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
8 - It reads your website's main page (or whatever URL you supply) and looks for
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
9 `Microformats`_ markup.
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
10 - It reads a configuration file where you describe which "silos" (*i.e.*
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
11 external services) you want to post your content to.
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
12 - It reads a local cache file to figure out which content has already been
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
13 posted where, so it only posts new content.
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
14 - It actually posts that content to each silo.
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
15
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
16
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
17 Supported Silos
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
18 ---------------
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
19
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
20 Right now, the following silos are supported:
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
21
6
6dc64a419a71 Add Twitter to list of support silos.
Ludovic Chabant <ludovic@chabant.com>
parents: 0
diff changeset
22 - `Mastodon`_: an open, federated social network and microblogging service.
6dc64a419a71 Add Twitter to list of support silos.
Ludovic Chabant <ludovic@chabant.com>
parents: 0
diff changeset
23 - `Twitter`_: a proprietary social network and microblogging service.
0
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
24 - Print: a debug silo that just prints entries in the console.
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
25
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
26
17
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
27 Installation
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
28 ------------
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
29
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
30 You can install SiloRider like any other Python tool::
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
31
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
32 pip install silorider
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
33
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
34 You can then check it installed correctly with::
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
35
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
36 silorider -h
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
37
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
38 You can also install from source by cloning the Git or Mercurial repository and
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
39 running::
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
40
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
41 pip install -e /path/to/silorider/repo
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
42
678278cb85b1 Add installation steps in README.
Ludovic Chabant <ludovic@chabant.com>
parents: 15
diff changeset
43
0
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
44 Quickstart
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
45 ----------
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
46
15
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
47 SiloRider will need to read a configuration file in `INI`_ format. The minimum
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
48 requirement is to define at least one "silo" using a ``silo:<name>`` section,
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
49 and to specify the url to one of your personal websites::
0
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
50
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
51 [silo:my_mastodon]
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
52 type: mastodon
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
53 url: https://mastodon.social
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
54
15
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
55 [urls]
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
56 my_blog: https://your.website.com
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
57
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
58 This defines one Mastodon silo to which you want to cross-post entries from
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
59 your blog at ``your.website.com``.
0
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
60
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
61 You can then run::
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
62
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
63 silorider auth my_mastodon
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
64
15
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
65 This command will authenticate your Mastodon account and provide SiloRider with
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
66 the permission to post to your timeline. The authorization tokens are stored in
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
67 a cache file that defaults to ``silorider.db``, next to the configuration file.
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
68 Later, this cache will also contain the list of entries already posted to each
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
69 silo.
0
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
70
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
71 Once authenticated, you can run::
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
72
15
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
73 silorider populate
0
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
74
15
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
75 This will populate the cache with the existing entries, since you probably
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
76 don't want the first run of SiloRider to cross-post your last dozen or so
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
77 entries in one go.
0
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
78
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
79 Later, when you post something new, you can then run::
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
80
15
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
81 silorider process
0
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
82
15
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
83 This will pick up the new entries and post them to Mastodon. You can run this
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
84 command again regularly... if there's something new, SiloRider will cross-post
cb1dc5c864d8 Specify URLs in the config file instead of in the CLI.
Ludovic Chabant <ludovic@chabant.com>
parents: 6
diff changeset
85 it to the configured silos. If not, it will just exit.
0
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
86
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
87
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
88 .. _POSSE: https://indieweb.org/POSSE
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
89 .. _Microformats: http://microformats.org/
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
90 .. _Mastodon: https://joinmastodon.org/
6
6dc64a419a71 Add Twitter to list of support silos.
Ludovic Chabant <ludovic@chabant.com>
parents: 0
diff changeset
91 .. _Twitter: https://twitter.com/
0
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
92 .. _INI: https://en.wikipedia.org/wiki/INI_file
a1b7a459326a Initial commit.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
93