EarthReader-Web 0.3.0

Earth Reader for Web

.. image:: https://raw.github.com/earthreader/web/master/artwork/icon_256x256.png


Earth Reader for Web
====================

Web frontend of Earth Reader.

Distributed under `AGPLv3`__ or later.

__ http://www.gnu.org/licenses/agpl-3.0.html


Install
-------

You can install Earth Reader for Web using ``pip``:

.. code-block:: console

$ pip install EarthReader-Web

Then you can use command ``earthreader``.

.. code-block:: console

$ earthreader -h


Repository
----------

*Repository* is a directory to store data. It can be inside of Dropbox_ or
`Google Drive`_ folder to be synchronized__ with other devices. You also
can synchronize the repository directory using rsync_.

If the path that doesn't exist yet is passed to CLI repository path argument or
``EARTHREADER_REPOSITORY`` environment variable the new folder will be
automatically created.

.. _Dropbox: https://www.dropbox.com/
.. _Google Drive: https://drive.google.com/
__ http://blog.earthreader.org/2013/12/sync/
.. _rsync: http://rsync.samba.org/


Standalone server
-----------------

You can run Earth Reader for Web using its standalone server:

.. code-block:: console

$ earthreader server /path/to/repository/dir
$ earthreader server -p 8080 /path/to/repository/dir # listen to 8080 port
$ earthreader server -d /path/to/repository/dir # debug mode

And then open ``http://localhost:<port>/`` with your browser.


WSGI server
-----------

Earth Reader for Web is actually an ordinary WSGI_-compliant web application,
so you can run it using your preferred WSGI server e.g. Gunicorn_, `mod_wsgi`_.
The WSGI endpoint is ``earthreader.web:app``. Note that you can provide
the path of repository by setting ``EARTHREADER_REPOSITORY`` environment
variable.

Note that you should manually invoke ``earthreader crawl`` command when
you run it using your preferred WSGI server while the standalone server
(``earthreader server`` command) automatically does it for you. We recommend
you to register ``earthreader crawl`` command to your ``crontab``.

For example, you can run it on Gunicorn:

.. code-block:: console

$ export EARTHREADER_REPOSITORY=/path/to/repository/dir
$ gunicorn earthreader.web:app

Or you can attach Earth Reader to Apache with mod_wsgi like this:

.. code-block:: apache

<VirtualHost *:80>
ServerName yourwebsite.com
WSGIDaemonProcess earthreader user=www-data group=www-data threads=1
WSGIScriptAlias / /var/wsgi/earthreader.wsgi

<Directory /var/wsgi/>
WSGIProcessGroup earthreader
WSGIApplicationGroup %{GLOBAL}

Order deny,allow
Allow from all
# We recommend you to use authorization for security.
AuthType Basic
AuthName "Private rss reader"
AuthUserFile /var/wsgi/earthreader.htpasswd
Require valid-user
</Directory>
</VirtualHost>

.. code-block:: python

#!/usr/bin/env python
#/var/wsgi/earthreader.wsgi
import sys
from earthreader.web import app as application

application.config.update(
REPOSITORY='/path/to/repository/dir'
)

And open ``http://yourwebsite.com/`` in your browser.

.. _WSGI: http://www.python.org/dev/peps/pep-3333/
.. _Gunicorn: http://gunicorn.org/
.. _mod_wsgi: http://code.google.com/p/modwsgi/


Crawler
-------

You can manually crawl feeds as well via CLI:

.. code-block:: console

$ earthreader crawl /path/to/repository/dir


Keyboard shortcuts
------------------

Vim-inspired keyboard shortcuts are also available:

- ``j``/``k``: Older/newer entry.
- ``n``/``p``: Next/previous subscription.
- ``o``: Open entry in new tab.
- ``r``: Refresh the feed.
- ``s``: Star/unstar.
- ``u`` or ``m``: Mark as unread.
- ``?``: This help message.


Links
-----

Earth Reader
http://earthreader.org/

libearth
https://github.com/earthreader/libearth

Git repository (GitHub)
https://github.com/earthreader/web

Issue tracker (GitHub)
https://github.com/earthreader/web/issues

Mailing list
[e-mail]

List archive
http://librelist.com/browser/earthreader/

Continuous integration (Travis)
https://travis-ci.org/earthreader/web

.. image:: https://travis-ci.org/earthreader/web.png?branch=master
:alt: Build Status
:target: https://travis-ci.org/earthreader/web


Demo
----

You can try Earth Reader web here:
http://try.earthreader.org/


Changelog
---------

Version 0.3.0
~~~~~~~~~~~~~

Released on February 24, 2015.

- Run crawler thread by default.
- Error code ``circular-refernce``, which is a typo, was renamed to
``circular-reference``.
- Fixed auto scroll when entry has images.
- Fixed a bug that raises ``BuildError``. [`#49`__]
- Became to need libearth 0.3.1 or later.
- Save theme setting.
- "Go to top" button on bottom.
- And a lot of changes (`Version 0.2.2`_).

__ https://github.com/earthreader/web/issues/49


Version 0.2.2
~~~~~~~~~~~~~

Released on February 24, 2015.

- Fixed a bug that enters a infinite loop when initilize
:class:`~earthreader.web.CategoryEntryGenerator`
- Fix open link.
- And a lot of changes (`Version 0.1.2`_).


Version 0.2.1
~~~~~~~~~~~~~

Released on July 16, 2014.

- Relative directory path on WSGI app. [`#42`__]
- Give correct permalink. [`#43`__]
- Workaround libearth 0.3.0 incompatibility.
- Entry list is cached by browser using ``Last-Modified`` and
``If-Modified-Since`` headers.

__ https://github.com/earthreader/web/issues/42
__ https://github.com/earthreader/web/issues/43


Version 0.2.0
~~~~~~~~~~~~~

Released on April 22, 2014.

- ``earthreader crawl`` command adds new options:

- ``-f``/``--feed-id`` crawls only the specified feed if present.
- ``-v``/``--verbose`` shows more detail information.

- Categories are folded at first.
- Keyboard shortcut for toggle folding category.
- Expand categories when click feed for mobile layout.
- Google reader style shortcuts.
- Mark all as read function. [`#28`__]
- Fixed a bug that "crawl now" button didn't work.
- Relative directory path on command line. [`#36`__]
- GUI launcher for OS X. [`#38`__]

__ https://github.com/earthreader/web/issues/28
__ https://github.com/earthreader/web/issues/36
__ https://github.com/earthreader/web/issues/38


Version 0.1.2
~~~~~~~~~~~~~

Released on February 24, 2015.

- Entry list is cached by browser using :mailheader:`Last-Modified` and
:mailheader:`If-Modified-Since` headers.
- Fix malformed session id on multi process.
- Fix error log when crawling.
- Force MIME type "test/html" when not given.
- Fix shortcut key.


Version 0.1.1
~~~~~~~~~~~~~

Released on January 10, 2014.

- Fixed ``ImportError`` when ``earthreader`` command is invoked on Python 3.
[`#25`__ by Yong Choi]
- The repository path argument format became consistent both for
``earthreader server`` and ``earthreader crawl`` commands.
[`#24`__]
- Close help overlay on ``escape`` key.
[`#27`__]
- Added ``--P``/``--profile``/``--linesman`` option, available only when
linesman_ is installed, to ``earthreader server`` comand.
- Continue crawling when some feed raises error.
- Fix crawling bug.
- Print error when failed to remove feed.
- Fixed some Unicode coding bugs on server side.
- ``-v``/``--verbose`` option prints detailed tracebacks of
crawler errors.
- Spinner UI while loading contents.

__ https://github.com/earthreader/web/pull/25
__ https://github.com/earthreader/web/issues/24
__ https://github.com/earthreader/web/issues/27
.. _linesman: https://pypi.python.org/pypi/linesman


Version 0.1.0
~~~~~~~~~~~~~

Released on December 23, 2013. Alpha version.