Browse Source

update documentation, copyright, CHANGELOG, AUTHORS and README

merge-requests/1/head
Carl Chenet 4 years ago
parent
commit
a4d767d347
13 changed files with 87 additions and 239 deletions
  1. +0
    -1
      AUTHORS
  2. +2
    -20
      CHANGELOG
  3. +6
    -11
      README.md
  4. +9
    -9
      docs/source/conf.py
  5. +39
    -100
      docs/source/configure.rst
  6. +3
    -5
      docs/source/index.rst
  7. +6
    -8
      docs/source/install.rst
  8. +0
    -38
      docs/source/plugins.rst
  9. +14
    -39
      docs/source/use.rst
  10. +2
    -2
      remindr.py
  11. +1
    -1
      remindr/cfgparse.py
  12. +1
    -1
      remindr/main.py
  13. +4
    -4
      scripts/remindr

+ 0
- 1
AUTHORS View File

@ -1,2 +1 @@
Antoine Beaupré <anarcat@debian.org>
Carl Chenet <chaica@ohmytux.com>

+ 2
- 20
CHANGELOG View File

@ -1,21 +1,3 @@
## [0.5] - 2017-05-05
## [0.1] - 2017-08-17
### Added
- manage rss feeds entries without id
## [0.4] - 2017-04-28
### Changed
- [hashtaglist] section is not mandatory any more
- bugfixes
## [0.3] - 2017-04-12
### Changed
- remove persistentlist dependency because unstable and use own cache storage
## [0.2] - 2017-04-11
### Changed
- register_feed2toot_app now able to generate credentials for any instance
- remove useless tweepy dependencies
## [0.1] - 2017-04-09
### Changed
- forking from feed2tweet
- initial release

+ 6
- 11
README.md View File

@ -1,6 +1,6 @@
### Remindr
Remindr automatically parses rss feeds, stores rss entries and posts reminders of the last ones to social networks, like the [Mastodon](https://joinmastodon.org) or ([Twitter](https://twitter.com).
Remindr automatically sends reminders about last blog entries on social networks, like the [Mastodon](https://joinmastodon.org) or ([Twitter](https://twitter.com).
For the full documentation, [read it online](https://remindr.readthedocs.org/en/latest/).
If you would like, you can [support the development of this project on Liberapay](https://liberapay.com/carlchenet/).
@ -43,17 +43,12 @@ Alternatively you can donate cryptocurrencies:
; Default visibility is public, but you can override it:
; toot_visibility=unlisted
[database]
database=remindr.db
[entrylist]
path_to_list=/etc/remindr/list.txt
[rss]
uri=https://carlchenetcom/feed/
[message]
message={title} {link}
[hashtaglist]
several_words_hashtags_list=hashtags.txt
[prefix]
en_prefix=My Last Blog Post:
fr_prefix=Mon dernier billet de blog :
* Launch Remindr


+ 9
- 9
docs/source/conf.py View File

@ -1,7 +1,7 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# feed2toot documentation build configuration file, created by
# remindr documentation build configuration file, created by
# sphinx-quickstart on Wed Dec 17 18:25:26 2014.
#
# This file is execfile()d with the current directory set to its
@ -46,7 +46,7 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = 'feed2toot'
project = 'remindr'
copyright = '2017, Carl Chenet <chaica@ohmytux.com>'
# The version info for the project you're documenting, acts as replacement for
@ -54,9 +54,9 @@ copyright = '2017, Carl Chenet <chaica@ohmytux.com>'
# built documents.
#
# The short X.Y version.
version = '1.0'
version = '0.1'
# The full version, including alpha/beta/rc tags.
release = '1.0'
release = '0.1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@ -179,7 +179,7 @@ html_static_path = ['_static']
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'feed2tootdoc'
htmlhelp_basename = 'remindrdoc'
# -- Options for LaTeX output ---------------------------------------------
@ -199,7 +199,7 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'feed2toot.tex', 'feed2toot Documentation',
('index', 'remindr.tex', 'remindr Documentation',
'Carl Chenet \\textless{}chaica@ohmytux.com.org\\textgreater{}', 'manual'),
]
@ -229,7 +229,7 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'feed2toot', 'feed2toot Documentation',
('index', 'remindr', 'remindr Documentation',
['Carl Chenet <chaica@ohmytux.com>'], 1)
]
@ -243,8 +243,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'feed2toot', 'feed2toot Documentation',
'Carl Chenet <chaica@ohmytux.com>', 'feed2toot', 'One line description of project.',
('index', 'remindr', 'remindr Documentation',
'Carl Chenet <chaica@ohmytux.com>', 'remindr', 'One line description of project.',
'Miscellaneous'),
]


+ 39
- 100
docs/source/configure.rst View File

@ -1,135 +1,74 @@
Configure Feed2toot
===================
Configure Remindr
=================
As a prerequisite to use Feed2toot, you need to authorize a Mastodon app for your account.
As a prerequisite to use Remindr, you need to authorize a Mastodon app for your account.
Just use the script register_feed2toot_app to register the feed2toot app for your account.::
Just use the script register_remindr_app to register the remindr app for your account.::
$ ./register_feed2toot_app
$ ./register_remindr_app
This app generates Mastodon app credentials needed by Feed2toot.
feed2toot_clientcred.txt and feed2toot_usercred.txt will be written in the current dir /home/chaica/progra/python/feed2toot.
This app generates Mastodon app credentials needed by Remindr.
remindr_clientcred.txt and remindr_usercred.txt will be written in the current dir /home/chaica/progra/python/remindr.
One connection is initiated to create the app.
Your password is *not* stored.
Mastodon instance url (defaults to https://mastodon.social):
Mastodon login:chaica@ohmytux.com
Mastodon password:
The feed2toot app was added to your preferences=>authorized apps page
The remindr app was added to your preferences=>authorized apps page
As described above, two files were created. You'll need them in the feed2toot configuration.
As described above, two files were created. You'll need them in the remindr configuration.
In order to configure Feed2toot, you need to create a feed2toot.ini file (or any name you prefer, finishing with the extension .ini) with the following parameters::
In order to configure Remindr, you need to create a remindr.ini file (or any name you prefer, finishing with the extension .ini) with the following parameters::
[mastodon]
instance_url=https://mastodon.social
; Here you need the two files created by register_feed2toot_app
user_credentials=/etc/feed2toot/credentials/feed2toot_usercred.txt
client_credentials=/etc/feed2toot/credentials/feed2toot_clientcred.txt
; Here you need the two files created by register_remindr_app
user_credentials=/etc/remindr/credentials/remindr_usercred.txt
client_credentials=/etc/remindr/credentials/remindr_clientcred.txt
; Default visibility is public, but you can override it:
; toot_visibility=unlisted
[cache]
cachefile=/var/lib/feed2toot/feed2toot.db
cache_limit=10000
; toot_visibility=public
[rss]
uri=https://www.journalduhacker.net/rss
uri_list=/etc/feed2toot//rsslist.txt
tweet={title} {link}
title_pattern=Open Source
title_pattern_case_sensitive=true
no_uri_pattern_no_global_pattern=true
[entrylist]
path_to_list=/etc/remindr/list.txt
[hashtaglist]
several_words_hashtags_list=/etc/feed2toot/hashtags.txt
[prefix]
fr_prefix=Mon dernier billet de blog :
en_prefix=My Last Blog Post:
For the [mastodon] section:
- instance_url: the url of your Mastodon instance
- user_credentials: a file with the user credentials, generated by the command register_feed2toot_app
- client_credentials: a file with the client credentials, generated by the command register_feed2toot_app
- user_credentials: a file with the user credentials, generated by the command register_remindr_app
- client_credentials: a file with the client credentials, generated by the command register_remindr_app
- toot_visibility: any of the valid options for the *visibility* field
`here`__.
Default is *public*, but *unlisted* prevents flooding
the instance's public timeline (which is more polite).
Default is *public*, but *unlisted* prevents flooding the instance's public timeline (which is more polite).
__ https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md#posting-a-new-status
For the [cache] section:
- cachefile: the path to the cache file storing ids of already tweeted links. Absolute path is mandatory. This file should always use the .db extension.
- cache_limit: length of the cache queue. defaults to 100.
For the [rss] section:
- uri: the url of the rss feed to parse
- uri_list: a path to a file with several adresses of rss feeds, one by line. Absolute path is mandatory.
- tweet: format of the tweet you want to post. It should use existing entries of the RSS fields like {title} or {link}. Launch it with this field empty to display all available entries.
- {one field of the rss feed}_pattern: takes a string representing a pattern to match for a specified field of each rss entry of the rss feed, like title_pattern or summary_pattern.
- {one field of the rss feed}_pattern_case_sensitive: either the pattern matching for the specified field should be case sensitive or not. Default to true if not specified.
- no_uri_pattern_no_global_pattern: don't apply global pattern (see above) when no pattern-by-uri is defined in the uri_list. Allows to get all entries of a rss in the uri_list because no pattern is defined so we match them all. Defaults to false, meaning the global patterns will be tried on every rss in the uri_list NOT HAVING specific patterns and so ONLY entries from the specific uri in the uri_list matching the global patterns will be considered.
For the [hashtaglist] section:
- several_words_hashtags_list: a path to the file containing hashtags in two or more words. Absolute path is mandatory. By default Feed2toot adds a # before every words of a hashtag. See documentation below for an example of this file.
Example of the list of hash tags
================================
The list of hash tags is a simple text file with one hash tag composed by several words on a single line::
free software community
open-source
Instead of having #free #software #community or #open-source in the resulting toot, you will have #freesoftwarecommunity and #opensource. You only have to identify the hash tags you frequently use in your RSS feeds and put them in this file to have well formatted hash tags in your toots.
List of rss feeds
=================
Simple list of rss feeds
------------------------
With the parameter **uri_list**, you can define a list of uri to use. Feed2toot is able to match specific patterns for each of the rss feeds from this list. Consider the following rss section of the configuration file::
[rss]
uri_list=/home/john/feed2toot/rsslist.txt
tweet={title} {link}
Now let's have a look at the =/home/john/feed2toot/rsslist.txt file::
https://www.journalduhacker.net/rss
https://carlchenet.com/feed
Each line of this file is a url to a rss feed. Pretty simple.
Match specific patterns of rss feeds in the uri_list files
----------------------------------------------------------
You can use specific pattern matching for uri in the uri_list file to filter some of the rss entries of a rss feed. Lets modify the previous file::
https://www.journalduhacker.net/rss|title|hacker,psql
https://carlchenet.com/feed|title|gitlab
Each line of this file starts with an uri, followed by a pipe (|), followed by the name of the available section to parse (see below), again followed by a pipe (|), followed by patterns, each pattern being separated from the other one by a semi-colon (,).
For the [entrylist] section:
In the example file above wee get every rss entries from the feed available at https://www.journalduhacker.net/rss where a substring in the title section of this entry matches either "hacker" or "psql". Specific patterns are not case sensitive. For the second line, we match every rss entries from the feed available at https://carlchenet.com/feed where a substring in the title section of this entry matches "gitlab".
- path_to_list: the path to the file containing the list of blog entries to remind people about.
Consider every entries of a rss feed from a uri in the uri_list file
--------------------------------------------------------------------
It is possible to get all entries from a rss feed available in the uri_list file. You need an option to deactivate the global pattern matching for uri in the uri_list NOT having specific patterns::
For the [prefix] section:
[rss]
...
no_uri_pattern_no_global_pattern=true
- {lang}_prefix: you should modify {lang} by a the 2-letter internation code of the language. It is going to be used to match the good language for both prefix and the entry of blog post to remind people about.
In you rsslist.txt, just don't give anything else than the needed feed url to get all the entries::
The entrylist file
==================
A file with at least 3 fields by line, each field being separated of the others by a space::
https://www.journalduhacker.net/rss|title|hacker,psql
https://carlchenet.com/feed|title|gitlab
https://blog.linuxjobs.fr/feed.php?rss
o en Automatically Send Toots To The Mastodon Social Network https://carlchenet.com/automatically-send-toots-to-the-mastodon-social-network/ #Mastodon
x fr Sur Mastodon, créer son compte de secours… ou tout perdre https://carlchenet.com/sur-mastodon-creer-son-compte-de-secours-ou-tout-perdre/ #Mastodon
x en Automatically boost cool toots on Mastodon with the Boost bot https://carlchenet.com/automatically-boost-cool-toots-on-mastodon-with-the-boost-bot/ #Mastodon
x en Cryptocurrencies On the New Social Network Mastodon #Mastodon #bitcoin #ethereum #monero
The last line of the file above only has the url of a rss feed. All entries from this feed will be tweeted.
Here are the details for this example::
How to display available sections of the rss feed
=================================================
Feed2toot offers the **--rss-sections** command line option to display the available section of the rss feed and exits::
- The first field is usually x, except for the line you want to start from, which uses 'o', as displayed in the example above (line 1).
- The second field is a 2-letter internation code for the language of your message, here we use 'en' or 'fr'. It should match the code in the {lang}_prefix of the configuration file, here en_prefix and fr_prefix in the configuration file.
- The third field is the title of your message.
- The fourth field is the url to your blog post.
- The fifth and following fields could be hashtags of whatever you wish to use.
$ feed2toot --rss-sections -c feed2toot.ini
The following sections are available in this RSS feed: ['title', 'comments', 'authors', 'link', 'author', 'summary', 'links', 'tags', id', 'author_detail', 'published'].

+ 3
- 5
docs/source/index.rst View File

@ -1,8 +1,7 @@
Documentation for the Feed2toot project
=======================================
Documentation for the Remindr project
=====================================
Feed2toot parses a RSS feed, extracts the last entries and sends them to Mastodon.
You'll find below anything you need to install, configure or run Feed2toot.
Remindr automatically sends toots/tweets from a user-defined list to remind people about the last blog entries using the social networks. You'll find below anything you need to install, configure or run Remindr.
Guide
=====
@ -13,7 +12,6 @@ Guide
install
configure
use
plugins
license
authors


+ 6
- 8
docs/source/install.rst View File

@ -1,13 +1,11 @@
How to install Feed2toot
========================
How to install Remindr
======================
From PyPI
^^^^^^^^^
$ pip3 install feed2toot
$ pip3 install remindr
From sources
^^^^^^^^^^^^
* You need at least Python 3.4.
* On some Linux Distribution **setuptools** package does not come with default python install, you need to install it.
* Install **PIP**::
@ -25,10 +23,10 @@ Alternatively, Setuptools may be installed to a user-local path::
* Untar the tarball and go to the source directory with the following commands::
$ tar zxvf feed2toot-0.5.tar.gz
$ cd feed2toot
$ tar zxvf remindr-0.1.tar.gz
$ cd remindr
* Next, to install Feed2toot on your computer, type the following command with the root user::
* Next, to install Remindr on your computer, type the following command with the root user::
$ python3 setup.py install
$ # or


+ 0
- 38
docs/source/plugins.rst View File

@ -1,38 +0,0 @@
Plugins
=======
Feed2toot supports plugins. Plugins offer optional features, not supported by default. Optional means you need a dedicated configuration and sometimes a dedicated external dependencies. What you need for each module is specified below.
InfluxDB
--------
The InfluxDB plugin allows to store already published tweets in a InfluxDB database.
Install the InfluxDB plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^
To install Feed2toot with the InfluxDB plugin, execute the following command.
From scratch::
# pip3 install feed2toot[influxdb]
Upgrading from a previous version, execute the followin command::
# pip3 install feed2toot[influxdb] --upgrade
Configuration
^^^^^^^^^^^^^
Below is the block of configuration to add in your feed2toot.ini::
[influxdb]
;host=127.0.0.1
;port=8086
user=influxuser
pass=V3ryS3cr3t
database=influxdb
measurement=tweets
- host: the host where the influxdb instance is. Defaults to 127.0.0.1
- port: the port where the influxdb instance is listening to. Defaults to 8086
- user: the user authorized to connect to the database. Mandatory (no default)
- pass: the password needed to connect to the database. Mandatory (no default)
- database: the name of the influxdb database to connect to. Mandatory (no default)
- measurement: the measurement to store the value into. Mandatory (no default)

+ 14
- 39
docs/source/use.rst View File

@ -1,56 +1,31 @@
Use Feed2toot
==============
After the configuration of Feed2toot, just launch the following command::
$ feed2toot -c /path/to/feed2toot.ini
Use Remindr
===========
After the configuration of Remindr, just launch the following command::
Run Feed2toot on a regular basis
=================================
Feed2toot should be launche on a regular basis in order to efficiently send your new RSS entries to Mastodon. It is quite easy to achieve with adding a line to your user crontab, as described below::
$ remindr -c /path/to/remindr.ini
@hourly feed2toot -c /path/to/feed2toot.ini
Run Remindr on a regular basis
==============================
Remindr should be launched on a regular basis in order to efficiently remind people about your blog posts using the social networks. It is quite easy to achieve with adding a line to your user crontab, as described below::
will execute feed2toot every hour. Or without the syntactic sugar in the global crontab file /etc/crontab::
0 11 * * * johndoe remindr -c /path/to/remindr.ini
0 * * * * johndoe feed2toot -c /path/to/feed2toot.ini
will execute remindr every day at 11AM.
Test option
===========
In order to know what's going to be sent to Mastodon without actually doing it, use the **--dry-run** option::
$ feed2toot --dry-run -c /path/to/feed2toot.ini
$ remindr --dry-run -c /path/to/remindr.ini
Debug option
============
In order to increase the verbosity of what's Feed2toot is doing, use the **--debug** option followed by the level of verbosity see [the the available different levels](https://docs.python.org/3/library/logging.html)::
$ feed2toot --debug -c /path/to/feed2toot.ini
Populate the cache file without posting tweets
==============================================
Starting from 0.8, Feed2toot offers the **--populate-cache** command line option to populate the cache file without posting to Mastodon::
$ feed2toot --populate-cache -c feed2toot.ini
populating RSS entry https://www.journalduhacker.net/s/65krkk
populating RSS entry https://www.journalduhacker.net/s/co2es0
populating RSS entry https://www.journalduhacker.net/s/la2ihl
populating RSS entry https://www.journalduhacker.net/s/stfwtx
populating RSS entry https://www.journalduhacker.net/s/qq1wte
populating RSS entry https://www.journalduhacker.net/s/y8mzrp
populating RSS entry https://www.journalduhacker.net/s/ozjqv0
populating RSS entry https://www.journalduhacker.net/s/6ev8jz
populating RSS entry https://www.journalduhacker.net/s/gezvnv
populating RSS entry https://www.journalduhacker.net/s/lqswmz
How to display available sections of the rss feed
=================================================
Starting from 0.8, Feed2toot offers the **--rss-sections** command line option to display the available section of the rss feed and exits::
In order to increase the verbosity of what's Remindr is doing, use the **--debug** option followed by the level of verbosity see [the the available different levels](https://docs.python.org/3/library/logging.html)::
$ feed2toot --rss-sections -c feed2toot.ini
The following sections are available in this RSS feed: ['title', 'comments', 'authors', 'link', 'author', 'summary', 'links', 'tags', id', 'author_detail', 'published'].
$ remindr --debug -c /path/to/remindr.ini
Using syslog
============
Feed2toot is able to send its log to syslog. You can use it with the following command::
Remindr is able to send its log to syslog. You can use it with the following command::
$ feed2toot --syslog=WARN -c /path/to/feed2toot.ini
$ remindr --syslog=WARN -c /path/to/remindr.ini

+ 2
- 2
remindr.py View File

@ -1,6 +1,6 @@
#!/usr/bin/env python3
# vim:ts=4:sw=4:ft=python:fileencoding=utf-8
# Copyright © 2015-2017 Carl Chenet <carl.chenet@ohmytux.com>
# Copyright © 2017 Carl Chenet <carl.chenet@ohmytux.com>
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
@ -24,7 +24,7 @@ class Remindr:
'''Remindr class'''
def __init__(self):
'''Constructor of the Feed2Toot class'''
'''Constructor of the Remidr class'''
self.main()
def main(self):


+ 1
- 1
remindr/cfgparse.py View File

@ -1,5 +1,5 @@
# -*- coding: utf-8 -*-
# Copyright © 2015-2017 Carl Chenet <carl.chenet@ohmytux.com>
# Copyright © 2017 Carl Chenet <carl.chenet@ohmytux.com>
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or


+ 1
- 1
remindr/main.py View File

@ -36,7 +36,7 @@ from remindr.getlastblogentry import getlastblogentry
from remindr.tootpost import tootpost
class Main(object):
'''Main class of Feed2toot'''
'''Main class of Remindr'''
def __init__(self):
self.main()


scripts/feed2toot → scripts/remindr View File


Loading…
Cancel
Save