generate documentation with sphinx - fix #27

SamR1 · Mar 15, 2020 · 3e0325e · 3e0325e
1 parent 1f81ed1
commit 3e0325e
Show file tree

Hide file tree

Showing 99 changed files with 19,471 additions and 81 deletions.
diff --git a/.gitignore b/.gitignore
@@ -17,3 +17,6 @@ tootrss_clientcred.txt
 tootrss_usercred.txt
 *.log
 /twootfeed.egg-info/
+
+## Doc
+/docsrc/build/
diff --git a/Makefile b/Makefile
@@ -13,9 +13,16 @@ clean:
 create-mastodon-cli:
 	$(PYTHON) twootfeed/utils/create_mastodon_client.py
 
+html:
+	rm -rf docsrc/build
+	rm -rf docs/*
+	touch docs/.nojekyll
+	$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	cp -a docsrc/build/html/. docs
+
 install:
 	test -d $(VENV) || virtualenv $(VENV) -p $(PYTHON_VERSION)
-	$(PIP) install -e .[test]
+	$(PIP) install -e .[test,doc]
 	test -e twootfeed/config.yml || cp twootfeed/config.example.yml twootfeed/config.yml
 
 serve:

diff --git a/Makefile.config b/Makefile.config
@@ -17,3 +17,9 @@ PIP = $(VENV)/bin/pip
 FLASK = $(VENV)/bin/flask
 PYTEST = $(VENV)/bin/py.test
 GUNICORN = $(VENV)/bin/gunicorn
+
+#Sphinx Docs
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= $(VENV)/bin/sphinx-build
+SOURCEDIR     = docsrc/source
+BUILDDIR      = docsrc/build
diff --git a/README.md b/README.md
@@ -20,87 +20,9 @@ The RSS feed displays only the original tweets (not the retweets) and toots, wit
 - source
 - location (only for Twitter)
 - numbers of retweets and likes for tweets and boosts and favourites for toots   
-(see examples below).  
 
-## Requirements
 
-- Python 3.6+
-- API keys Twitter and/or Mastodon 
-
-
-## Installation and configuration
-
-- Install from pip
-
-```bash
-$ pip install twootfeed
-```
-
-- Initialize the configuration file
-```bash
-$ twootfeed_init
-```
-
-- Fill in fields for the client(s) you will use in **'~/.config/twootfeed/config.yml'** :
-  - for **Twitter** : see https://apps.twitter.com  
-  copy/paste the Twitter API key values in **config.yml** file ('_consumerKey_' and '_consumerSecret_')
-  - for **Mastodon** : see [Python wrapper for the Mastodon API](https://mastodonpy.readthedocs.io/)  
-  use the included script which will register your app and prompt you to log in, creating the credential files for you.
-  ```bash
-  $ twootfeed_create_mastodon_cli
-  ```
-  Update the [feed and app parameters](https://github.com/SamR1/python-twootfeed/wiki/Application-parameters).
-
-
-- The files location can be changed with the following environment variables:
-
-| variable               | description                                   | app default value                                                                         |
-|------------------------|-----------------------------------------------| ------------------------------------------------------------------------------------------|
-| `TWOOTFEED_CONFIG_DIR` | configuration and credentials files directory | **'~/.config/twootfeed/'**                                                                |
-| `TWOOTFEED_CONFIG_FILE`| config file full path                         | config dir + **'config.yml'** => with default value: **'~/.config/twootfeed/config.yml'** |
-| `TWOOTFEED_LOG`        | application log file                          | _no default value (log printed on the console)_                                           |
-
-- Start the app
-```bash
-$ twootfeed
-```
-
-## Usage 
-
-The RSS feeds are available on these urls:  
-  - for Twitter: http://localhost:8080/<keywords> or http://localhost:8080/tweets/<keywords>
-  - for Mastodon: 
-    - search:
-        - keyword as a hashtag: http://localhost:8080/toots/<hashtag> (without the leading #)
-        - query: http://localhost:8080/toot_search/<query>
-    - connected user favourites: http://localhost:8080/toot_favorites
-
-
-## Examples 
-
-### Search on Twitter 
-
-![Twitter search](https://raw.githubusercontent.com/SamR1/python-twootfeed/master/images/twitter.png)  
-
-Results in RSS Feed:  
-![RSS Feed](https://raw.githubusercontent.com/SamR1/python-twootfeed/master/images/RSSFeed.png)  
-
-Display on FreshRSS, a great free self-hosted aggregator (https://github.com/FreshRSS/FreshRSS):   
-![FreshRSS](https://raw.githubusercontent.com/SamR1/python-twootfeed/master/images/FreshRSS.png)  
-
-### Search on Mastodon
-
-![Mastodon search](https://raw.githubusercontent.com/SamR1/python-twootfeed/master/images/mastodon.png)
-
-Results in RSS Feed:  
-![Mastodon Feed](https://raw.githubusercontent.com/SamR1/python-twootfeed/master/images/MastodonRSSFeed.png) 
-
-Display on FreshRSS:  
-![Mastodon FreshRSS](https://raw.githubusercontent.com/SamR1/python-twootfeed/master/images/MastodonFreshRSS.png)  
-
-
-## Contribute
-see [Quick start for developers](https://github.com/SamR1/python-twootfeed/wiki/Quick-start-for-developers)
+➡️ see [documentation](https://samr1.github.io/python-twootfeed/index.html) for installation instructions and features.  
 
 
 ## Contributors

diff --git a/docs/.buildinfo b/docs/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 9bb041ae8d48f10f011ae9f45d95b00f
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/images/FreshRSS.png → docs/_images/FreshRSS.png b/images/FreshRSS.png → docs/_images/FreshRSS.png
diff --git a/images/MastodonFreshRSS.png → docs/_images/MastodonFreshRSS.png b/images/MastodonFreshRSS.png → docs/_images/MastodonFreshRSS.png
diff --git a/images/MastodonRSSFeed.png → docs/_images/MastodonRSSFeed.png b/images/MastodonRSSFeed.png → docs/_images/MastodonRSSFeed.png
diff --git a/images/RSSFeed.png → docs/_images/RSSFeed.png b/images/RSSFeed.png → docs/_images/RSSFeed.png
diff --git a/images/mastodon.png → docs/_images/mastodon.png b/images/mastodon.png → docs/_images/mastodon.png
diff --git a/images/twitter.png → docs/_images/twitter.png b/images/twitter.png → docs/_images/twitter.png
diff --git a/docs/_sources/changelog.md.txt b/docs/_sources/changelog.md.txt
@@ -0,0 +1,145 @@
+# Change log
+
+## Version 0.6.6 (2019/10/20)
+
+#### Misc
+
+* Update dependencies
+
+
+## Version 0.6.5 (2019/09/23)
+
+#### Bugs Fixed
+
+* [Issue 25](https://github.com/SamR1/python-twootfeed/issues/25) - toot_search route returns 404 error
+
+In this release 1 issue was closed.
+
+
+## Version 0.6.4 (2019/08/31)
+
+#### Misc
+
+* Update dependencies
+
+
+## Version 0.6.3 (2019/05/05)
+
+#### Bugs Fixed
+
+* [Issue 24](https://github.com/SamR1/python-twootfeed/issues/24) - return the correct HTTP code status when no keys are provided
+
+#### Misc
+
+* Update dependencies
+
+In this release 1 issue was closed.
+
+
+## Version 0.6.2 (2019/01/26)
+
+#### New Features
+
+* [Issue 23](https://github.com/SamR1/python-twootfeed/issues/23) - [Mastodon] add a new search route
+* [Issue 22](https://github.com/SamR1/python-twootfeed/issues/22) - The number of workers for the HTTP Server can be set
+* [Issue 21](https://github.com/SamR1/python-twootfeed/issues/21) - [Mastodon] use pagination to get toots
+
+In this release 3 issues were closed.
+
+
+## Version 0.6.1 (2019/01/25)
+
+#### New Features
+
+* [Issue 19](https://github.com/SamR1/python-twootfeed/issues/19) - Change environment variables
+
+#### Bugs Fixed
+
+* [Issue 20](https://github.com/SamR1/python-twootfeed/issues/20) - Limit items in feed to avoid error or time-out
+* [Issue 18](https://github.com/SamR1/python-twootfeed/issues/18) - [Mastodon] fix reference characters in items title
+
+In this release 3 issues were closed.
+
+
+## Version 0.6.0 (2019/01/23)
+
+#### New Features
+
+* twootfeed is now available on PyPI
+
+#### Bugs Fixed
+
+* [Issue 17](https://github.com/SamR1/python-twootfeed/issues/17) - [Twitter] the name used in url is the display name and not the username
+
+#### Misc
+* Python 3.7 support (since Tweepy 3.7 support)
+* Refactor
+* Continuous integration and tests coverage
+
+In this release 1 issue was closed.
+
+
+## Version 0.5.1 (2018-10-17)
+
+#### Misc
+* Performance improvements (code refactoring)
+* Use of Gunicorn for Production environments
+
+
+## Version 0.5.0 - Mastodon extended support (2018-10-14)
+
+#### New Features
+
+* [Issue 10](https://github.com/SamR1/python-twootfeed/issues/10) - add Mastodon support
+
+#### Bugs Fixed
+* [Issue 16](https://github.com/SamR1/python-twootfeed/issues/16) - [Twitter] long tweets are truncated
+* [Issue 15](https://github.com/SamR1/python-twootfeed/issues/15) - [Twitter] Images are no longer displayed
+* [Issue 2](https://github.com/SamR1/python-twootfeed/issues/2) - handle the tweeperror "Rate limit exceeded"
+
+#### Misc
+* Major refactor
+
+In this release 4 issues were closed.
+
+
+## Version 0.4.0 - make support (2018-04-01)
+
+#### Misc
+* Adding Makefile to ease install and starting the server (see README)
+
+
+## Version 0.3.0 - Mastodon favorites support (2017-12-07)
+
+#### New Features
+Thanks to @georgedorn for adding:
+* [PR 14](https://github.com/SamR1/python-twootfeed/pull/14) - Mastodon Favorites feed, mastodon client script, refactor
+  * rss feed generation with authenticated user's favorites
+  * script to register the app and generate credentials for Mastodon
+
+
+## Version 0.2.1 (2017-05-03)
+
+#### Misc
+* Minor fixes
+
+
+## Version 0.2.0 (2017-04-18)
+
+#### New Features
+* [Issue 10](https://github.com/SamR1/python-twootfeed/issues/10) - add Mastodon support
+
+In this release 1 issue was closed.
+
+
+## Version 0.1.0 (2017-04-18)
+
+#### New Features
+* [Issue 4](https://github.com/SamR1/python-twootfeed/issues/4) - Using Flask instead of Django
+* [Issue 3](https://github.com/SamR1/python-twootfeed/issues/3) - include query in RSS Feed Description
+* [Issue 1](https://github.com/SamR1/python-twootfeed/issues/1) - externalize the Twitter API keys
+
+#### Bugs Fixed
+* [Issue 5](https://github.com/SamR1/python-twootfeed/issues/5) - display all media
+
+In this release 4 issues were closed.
diff --git a/docs/_sources/features.rst.txt b/docs/_sources/features.rst.txt
@@ -0,0 +1,68 @@
+Features
+########
+
+Description
+~~~~~~~~~~~
+
+**twootfeed** generate an RSS feed from **Twitter** or **Mastodon** search and from **Mastodon** bookmarks/favorites.
+
+The feed displays only the original tweets (not the retweets) and toots, with:
+
+- links to :
+
+    - the tweet on Twitter or toot on Mastodon
+    - hashtags
+    - usernames
+
+- URLs
+- images
+- source
+- location (only for Twitter)
+- numbers of retweets and likes for tweets and boosts and favourites for toots
+
+
+
+.. warning::
+
+    **twootfeed** was originally developed for personal use.
+    Mastodon bookmarks/favorites toots are displayed for user associated to API key.
+
+
+Examples
+~~~~~~~~
+
+- Search on Twitter
+
+.. figure:: _images/twitter.png
+   :alt: Twitter search
+   :figclass: doc-img
+
+Results in RSS Feed:
+
+.. figure:: _images/RSSFeed.png
+   :alt: RSS Feed
+   :figclass: doc-img
+
+Display on FreshRSS, a great free self-hosted aggregator (https://github.com/FreshRSS/FreshRSS):
+
+.. figure:: _images/FreshRSS.png
+   :alt: FreshRSS
+   :figclass: doc-img
+
+- Search on Mastodon
+
+.. figure:: _images/mastodon.png
+   :alt: Mastodon search
+   :figclass: doc-img
+
+Results in RSS Feed:
+
+.. figure:: _images/MastodonRSSFeed.png
+   :alt: Mastodon Feed
+   :figclass: doc-img
+
+Display on FreshRSS:
+
+.. figure:: _images/MastodonFreshRSS.png
+   :alt: Mastodon FreshRSS
+   :figclass: doc-img
diff --git a/docs/_sources/how-to-developers.rst.txt b/docs/_sources/how-to-developers.rst.txt
@@ -0,0 +1,51 @@
+Quick start for developers
+##########################
+
+Dependencies
+~~~~~~~~~~~~
+
+- `Flask  <http://flask.pocoo.org/>`_
+- `Feedgenerator  <https://pypi.python.org/pypi/feedgenerator)>`_
+- `Tweepy  <https://github.com/tweepy/tweepy>`_ (only tested with the `Twitter Standard API <https://developer.twitter.com/en/docs/tweets/search/overview/standard.html>`_)
+- `Mastodon.py  <https://github.com/halcy/Mastodon.py>`_
+- `pytz  <https://pypi.python.org/pypi/pytz/>`_
+- `pyYAML  <https://github.com/yaml/pyyaml>`_
+- `BeautifulSoup  <https://pypi.python.org/pypi/beautifulsoup4>`_
+- `gunicorn  <https://gunicorn.org/>`_
+
+
+Installation
+~~~~~~~~~~~~
+
+- Clone this repo :
+
+.. code-block:: bash
+
+    $ git clone https://github.com/SamR1/python-twootfeed.git
+
+
+- Install Python virtualenv and packages
+
+.. code-block:: bash
+
+    $ cd python-twootfeed
+    $ make install
+
+
+- Fill in fields for the client(s) you will use in **python-twootfeed/config.yml** (see next step for API keys).
+
+- Get API Keys (see `installation <installation.html#installation>`_)
+
+- Start the server
+
+.. code-block:: bash
+
+    $ make serve
+
+
+Tests
+~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    $ make test