aboutsummaryrefslogtreecommitdiffhomepage
path: root/docs/en
diff options
context:
space:
mode:
authorNicolas Lœuillet <nicolas.loeuillet@smile.fr>2015-10-21 14:14:51 +0200
committerNicolas Lœuillet <nicolas.loeuillet@smile.fr>2015-10-21 14:14:51 +0200
commit59e91bc8931a386974a3817e9849aad1ca7fc186 (patch)
tree4bd4f99cff41e32c3820f1770d5500c96630c32f /docs/en
parenta4e1ddf2d64bba7c7e28459ccc6738a9a9e23e71 (diff)
downloadwallabag-59e91bc8931a386974a3817e9849aad1ca7fc186.tar.gz
wallabag-59e91bc8931a386974a3817e9849aad1ca7fc186.tar.zst
wallabag-59e91bc8931a386974a3817e9849aad1ca7fc186.zip
add docs
Diffstat (limited to 'docs/en')
-rw-r--r--docs/en/Administrator/hidden_options.rst85
-rw-r--r--docs/en/Administrator/install.rst200
-rw-r--r--docs/en/Administrator/multiusers.rst47
-rw-r--r--docs/en/Administrator/sessions.rst26
-rw-r--r--docs/en/Administrator/update.rst30
-rw-r--r--docs/en/Developer/create_new_theme.rst4
-rw-r--r--docs/en/Developer/git_repo.rst29
-rw-r--r--docs/en/Developer/write_config_files.rst52
-rw-r--r--docs/en/User/configure_wallabag.rst118
-rw-r--r--docs/en/User/epub_conversion.rst32
-rw-r--r--docs/en/User/framabag_account_creation.rst49
-rw-r--r--docs/en/User/import_export.rst107
-rw-r--r--docs/en/User/issue_with_article.rst36
-rw-r--r--docs/en/User/organize_articles.rst109
-rw-r--r--docs/en/User/read_an_article.rst63
-rw-r--r--docs/en/User/rss_feed.rst41
-rw-r--r--docs/en/User/save_your_first_article.rst226
-rw-r--r--docs/en/User/search.rst21
-rw-r--r--docs/en/conf.py87
-rw-r--r--docs/en/index.rst57
-rw-r--r--docs/en/requirements.txt2
-rw-r--r--docs/en/user/configuration.rst61
-rw-r--r--docs/en/user/create_account.rst43
-rw-r--r--docs/en/user/first_article.rst79
-rw-r--r--docs/en/user/login.rst20
25 files changed, 1624 insertions, 0 deletions
diff --git a/docs/en/Administrator/hidden_options.rst b/docs/en/Administrator/hidden_options.rst
new file mode 100644
index 00000000..5cf0b22e
--- /dev/null
+++ b/docs/en/Administrator/hidden_options.rst
@@ -0,0 +1,85 @@
1Hidden options
2==============
3
4Caution
5-------
6
7**Be careful**, this section is destined to advanced users. We are going
8to modify an important wallabag configuration file,
9``inc/poche/config.inc.php``. It is therefore advised to do a backup of
10this file before you proceed. **Any error occuring during the
11modification of a wallabag file could lead to malfunctions**.
12
13This file is created when you install wallabag. Install wallabag, do a
14backup copy of the file, then open it in your favorite text editor.
15
16In this file, there are some options that are not, as of now, available
17in the **config** page of wallabag.
18
19Modification of advanced options
20--------------------------------
21
22Each option is defined this way:
23
24::
25
26 @define ('OPTION_NAME', 'Value');
27
28For each line, you can only modify the ``Value`` field.
29
30Here is the list of each option you can change:
31
32- ``HTTP_PORT`` (default: ``80``) : the HTTP port of your web server.
33 You may need to change it if your server is behind a proxy. Accepted
34 values: number
35- ``SSL_PORT`` (default: ``443``) : the HTTP port of your web server.
36 You may need to change it if your server use SSLH. Accepted values:
37 number
38- ``MODE_DEMO`` (default : ``FALSE)``: If you ever wanted to set up a
39 demonstration server… Accepted values: ``TRUE`` or ``FALSE``.
40- ``DEBUG_POCHE`` (default: ``FALSE``) : if you encounter some problems
41 with wallabag, we may ask you to active Debug mode. Accepted values:
42 ``TRUE`` or ``FALSE``. Check the logs in cache/log.txt after
43 activating that.
44- ``ERROR_REPORTING`` (default : ``E_ALL & ~E_NOTICE``) : Set to
45 ``E_ALL`` if needed to look for eventual PHP errors.
46- ``DOWNLOAD_PICTURES`` (default: ``FALSE``) : Allows wallabag to fetch
47 images from the articles you save on your server, instead of fetching
48 only the text. We prefer to let you activate this option yourself.
49 Accepted values: ``TRUE`` or ``FALSE``.
50- ``REGENERATE_PICTURES_QUALITY`` (default : ``75``) : In order to
51 avoid security problems, pictures are regenerated if you activate the
52 download of pictures. This is the percentage of quality at which they
53 are saved. Increase that numbler if you want better quality, lower if
54 you need better performances.
55- ``SHARE_TWITTER`` (default: ``TRUE``) : enables Twitter sharing.
56 Accepted values: ``TRUE`` or ``FALSE``.
57- ``SHARE_MAIL`` (default: ``TRUE``) : enables mail sharing. Accepted
58 values: ``TRUE`` or ``FALSE``.
59- ``SHARE_EVERNOTE``\ (default : ``FALSE``) : enables sharing with your
60 Evernote account. Accepted values: ``TRUE`` or ``FALSE``.
61- ``SHARE_DIASPORA`` (default : ``FALSE``) : enables to share an
62 article on your Diaspora account.
63- ``DIASPORA_URL`` (default : ``http://diasporapod.com``) : The URL of
64 your Diaspora\* pod
65- ``CARROT`` (default : ``FALSE``) : Like Flattr, it’s a service to
66 give small amounts of money to a web page. See http://carrot.org/
67- ``SHARE_SHAARLI`` (default: ``FALSE``) : enables sharing via your
68 Shaarli installation (Shaarli is an open-source bookmark manager).
69 Accepted values: ``TRUE`` or ``FALSE``.
70- ``SHAARLI_URL`` (default: ``'http://myshaarliurl.com'``) : defines
71 your Shaarli installation URL. Accepted values: an URL.
72- ``FLATTR`` (default: ``TRUE``) : enables the possibility to Flattr an
73 article (`Flattr is a microdonation platform`_). If an article is
74 Flattr-able, an icon will be displayed, allowing you to send a
75 microdonation to the author. Accepted values: ``TRUE`` or ``FALSE``.
76- ``SHOW_PRINTLINK`` (default: ``'1'``) : enables the Print button for
77 articles. Accepted values: ``'1'`` to enable or ``'0'`` to disable.
78- ``SHOW_READPERCENT`` (default: ``'1'``) : enables the reading
79 progress on articles (working on the ``default``, ``dark``,
80 ``dmagenta``, ``solarized``, ``solarized-dark`` themes). Accepted
81 values: ``'1'`` to enable or ``'0'`` to disable.
82- ``PAGINATION`` (default: ``'12'``) : defines the number of articles
83 that are displayed on a list. Accepted values: number.
84
85.. _Flattr is a microdonation platform: http://en.wikipedia.org/wiki/Flattr
diff --git a/docs/en/Administrator/install.rst b/docs/en/Administrator/install.rst
new file mode 100644
index 00000000..006d8708
--- /dev/null
+++ b/docs/en/Administrator/install.rst
@@ -0,0 +1,200 @@
1Download and install wallabag
2=============================
3
4I don’t want to install wallabag
5--------------------------------
6
7If you can’t or don’t want to install Wallabag on your server, we
8suggest you create a free account on `Framabag`_ which uses our
9software (see :ref:`Framabag account creation`).
10
11I want to install wallabag
12--------------------------
13
14I want to download wallabag manually
15~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16
17`Download the latest wallabag version`_ and unpack it:
18
19::
20
21 wget http://wllbg.org/latest
22 unzip latest
23 mv wallabag-version-number wallabag
24
25Copy the files on your web server. For Ubuntu/Debian, it is the
26directory /var/www/html/ :
27
28::
29
30 sudo mv wallabag /var/www/html/
31
32Then, jump off to next section.
33
34I want to download wallabag via composer
35~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36
37You need to install composer:
38
39::
40
41 curl -s http://getcomposer.org/installer | php
42
43Next, on your web server, run this command:
44
45::
46
47 composer create-project wallabag/wallabag . dev-master
48
49All is downloaded into the current folder.
50
51Prerequisites for your web server
52^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
53
54Wallabag requires that several components to be installed on your web
55server. To make sure your server has all the prerequisites, open in your
56browser the page ``http://monserveur.com/wallabag/install/index.php``.
57
58The components are:
59
60- `PHP 5.3.3 or above`_ **with `PDO`_ support**
61- `XML for PHP`_
62- `PCRE`_
63- `ZLib`_ (otherwise, the processing of compressed pages will be
64 affected)
65- `mbstring`_ anb/or `iconv`_ (otherwise some pages will not be read -
66 even in English)
67- The `DOM/XML`_ extension
68- `Data filtering`_
69- `GD`_ (otherwise, pictures will not be saved)
70- `Tidy for PHP`_ (otherwise, you may encounter problems with some
71 pages)
72- `cURL`_ with ``Parallel URL fetching`` (optionnal)
73- `Parse ini file`_
74- `allow\_url\_fopen`_ (optionnal if cURL is installed)
75- `gettext`_ (required for multi-language support)
76
77Install the missing components before to proceed. For example, to
78install Tidy on Ubuntu/Debian:
79
80::
81
82 sudo apt-get install php5-tidy
83 sudo service apache2 reload
84
85Note : if you’re using IIS as a webserver, you have to disable
86*Anonymous Authentication* and `enable *Basic Authentication*`_ in order
87to be able to login.
88
89Twig installation
90^^^^^^^^^^^^^^^^^
91
92wallabag is build with Twig, a template library. You have to download it
93for wallabag to work. If you cannot install ``composer`` (for example in
94the case of shared hosting), we offer you to download a file which
95includes ``Twig``. This file can be downloaed from the page
96``http://myservur.com/wallabag/install/index.php`` (section TWIG
97INSTALLATION) or directly at http://wllbg.org/vendor. Uncompress it in
98your wallabag directory.
99
100Otherwise, you can use Composer to install ``Twig`` by launching
101``composer`` from your wallabag directory (in the case of Ubuntu/Debian
102too: /var/www/html/wallabag/) by following the commands written on
103screen:
104
105::
106
107 curl -s http://getcomposer.org/installer | php
108 php composer.phar install
109
110Creation of the database.
111^^^^^^^^^^^^^^^^^^^^^^^^^
112
113Wallabag can be installed on different types of databases:
114
115- `SQLite`_. The easiest system of all. No extra configuration needed.
116- `MySQL`_. A well known database system, which is in most cases more
117 efficient than SQLite.
118- `PostgreSQL`_. Some people found it better than MySQL.
119
120We advice you to use MySQL because it is more efficient. In this case,
121you should create a new database (for example ``wallabag``), a new user
122(for example ``wallabag``) and a password (here ``YourPassWord``). To do
123this, you can use ``phpMyAdmin``, or launch the following commands:
124
125::
126
127 mysql -p -u root
128 mysql> CREATE DATABASE wallabag;
129 mysql> GRANT ALL PRIVILEGES ON `wallabag`.* TO 'wallabag'@'localhost' IDENTIFIED BY 'VotreMotdePasse';
130 mysql> exit
131
132*Note:* If you’re using MySQL or Postgresql, you have to **fill all the
133fields**, otherwise the installation will not work and an error message
134will tell you what’s wrong. You must create the database that you will
135use for wallabag manually with a tool like PHPMyAdmin or the console.
136
137Permissions
138~~~~~~~~~~~
139
140Your web server needs a writing access to the ``assets``, ``cache`` and
141``db`` directories. Otherwise, a message will report that the
142installation is impossible:
143
144::
145
146 sudo chown -R www-data:www-data /var/www/html/wallabag
147
148Installation of wallabag. At last.
149~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
150
151Access to wallabag from your web browser:
152``http://votreserveur.com/wallabag``. If your server is correctly
153configured, you directly reach the setup screen.
154
155Select the type of database (``sqlite``, ``mysql`` or ``postgresql``)
156and fill the information about your database. In the case of the databse
157MySQL created before, the standard configuration will be:
158
159::
160
161 Database engine: MySQL
162 Server: localhost
163 Database: wallabag
164 Username: wallabag
165 Password: YourPassWord
166
167Finally, Create your first user and his/her password (different from the
168database user).
169
170Wallabag is now installed.
171
172Login
173-----
174
175From your web browser, you reach the login screen: fill your username
176and your password to connect to your account.
177
178Enjoy!
179
180.. _SQLite: http://php.net/manual/fr/book.sqlite.php
181.. _MySQL: http://php.net/manual/fr/book.mysql.php
182.. _PostgreSQL: http://php.net/manual/fr/book.pgsql.php
183.. _Framabag: https://framabag.org/
184.. _Download the latest wallabag version: http://wllbg.org/latest
185.. _PHP 5.3.3 or above: http://php.net/manual/fr/install.php
186.. _PDO: http://php.net/manual/en/book.pdo.php
187.. _XML for PHP: http://php.net/fr/xml
188.. _PCRE: http://php.net/fr/pcre
189.. _ZLib: http://php.net/en/zlib
190.. _mbstring: http://php.net/en/mbstring
191.. _iconv: http://php.net/en/iconv
192.. _DOM/XML: http://php.net/manual/en/book.dom.php
193.. _Data filtering: http://php.net/manual/fr/book.filter.php
194.. _GD: http://php.net/manual/en/book.image.php
195.. _Tidy for PHP: http://php.net/fr/tidy
196.. _cURL: http://php.net/fr/curl
197.. _Parse ini file: http://uk.php.net/manual/en/function.parse-ini-file.php
198.. _allow\_url\_fopen: http://www.php.net/manual/fr/filesystem.configuration.php#ini.allow-url-fopen
199.. _gettext: http://php.net/manual/fr/book.gettext.php
200.. _enable *Basic Authentication*: https://technet.microsoft.com/en-us/library/cc772009%28v=ws.10%29.aspx
diff --git a/docs/en/Administrator/multiusers.rst b/docs/en/Administrator/multiusers.rst
new file mode 100644
index 00000000..a4053aae
--- /dev/null
+++ b/docs/en/Administrator/multiusers.rst
@@ -0,0 +1,47 @@
1.. _`Multi users`:
2
3Multi users
4===========
5
6Create a new account
7--------------------
8
9Administrator mode
10------------------
11
12If you want to use wallabag with several persons, you can create new
13accounts from the configuration page.
14
15At the bottom of this page there is a form where you should input a user
16name and a password.
17
18It is now possible to login to this account from the login page of
19wallabag.
20
21No information are shared among the accounts.
22
23Open registration mode
24----------------------
25
26Starting from version 1.9, the administrator can let users register by
27themselves. This is done by changing the following lines in the
28configuration file:
29
30::
31
32 // registration
33 @define ('ALLOW_REGISTER', FALSE);
34 @define ('SEND_CONFIRMATION_EMAIL', FALSE);
35
36Then, a user will be able to enter his/her user name and password to
37create his/her own account. Depending on the configuration, a
38confimation email can be sent to users who gave an email address.
39
40Remove an account
41-----------------
42
43It is possible to remove your own account from the configuration page.
44You simply have to enter your password and to ask for the removal.
45
46Of course, when there is only one account, it is impossible to remove
47it.
diff --git a/docs/en/Administrator/sessions.rst b/docs/en/Administrator/sessions.rst
new file mode 100644
index 00000000..7dbae257
--- /dev/null
+++ b/docs/en/Administrator/sessions.rst
@@ -0,0 +1,26 @@
1Session issues
2==============
3
4If you end up disconnected even while checking the *Stay signed in
5checkbox*, please run the following commands as root (or with sudo) :
6
7::
8
9 mkdir /var/lib/wallabag-sessions
10 chown www-data:www-data /var/lib/wallabag-sessions
11
12*NOTE : The www-data user and group may not exist, you may use
13``chown http:http /var/lib/wallabag-sessions`` instead*
14
15Then, using apache add:
16``php_admin_value session.save_path /var/lib/wallabag-sessions`` to your
17apache vhost, for instance ``wallabag-apache.conf`` Finally, restart
18apache, for instance like this : ``/etc/init.d/apache2 restart``
19
20If you’re using nginx, add
21``php_admin_value[session.save_path] = /var/lib/wallabag-sessions`` in
22your nginx configuration file. Then, restart nginx :
23``/etc/init.d/nginx restart``
24
25*NOTE : If you’re using systemd, you should do
26``systemctl restart apache2`` (or nginx).*
diff --git a/docs/en/Administrator/update.rst b/docs/en/Administrator/update.rst
new file mode 100644
index 00000000..7b799bb3
--- /dev/null
+++ b/docs/en/Administrator/update.rst
@@ -0,0 +1,30 @@
1Update wallabag
2===============
3
4Update an existing wallabag installation
5----------------------------------------
6
7In order to update your installation, download and unzip the archive
8into your installation folder. For example on Ubuntu/Debian:
9
10::
11
12 wget http://wllbg.org/latest
13 unzip latest
14 rsync -ur wallabag-version-number/* /var/www/html/wallabag/ # could be another location such as /srv/html, /usr/share/nginx/html
15
16After that, just access wallabag in your browser and follow the
17instructions to finish the update.
18
19You can verify at the bottom of the configuration page that you’re
20running the last version.
21
22**If it fails**, just delete the ``install`` folder and clear the cache:
23
24::
25
26 cd /var/www/html/wallabag/
27 rm -r cache/* install/
28
29Clearing the cache is also possible in the configuration page, clicking
30on the link ``Delete Cache``.
diff --git a/docs/en/Developer/create_new_theme.rst b/docs/en/Developer/create_new_theme.rst
new file mode 100644
index 00000000..5731eb11
--- /dev/null
+++ b/docs/en/Developer/create_new_theme.rst
@@ -0,0 +1,4 @@
1Create new theme
2================
3
4TODO
diff --git a/docs/en/Developer/git_repo.rst b/docs/en/Developer/git_repo.rst
new file mode 100644
index 00000000..4fa5c608
--- /dev/null
+++ b/docs/en/Developer/git_repo.rst
@@ -0,0 +1,29 @@
1Git repository
2==============
3
4If you wish to contribute to the project by suggesting new features or
5by fixing some bugs, please follow the recommendations below regarding
6the git repository available at https://github.com/wallabag/wallabag.
7
8Current state
9-------------
10
11To manage the different versions of wallabag, we use Git.
12
13There are multiple branches for the source code of wallabag web app:
14
15- ``master`` branch : this is the stable branch, downloaded by those
16 who wish to install wallabag for their own use.
17- ``dev`` branch : before being added on ``master`` branch, all bug
18 fixes and new features must go on that branch. This branch is not
19 recommended for production use.
20- ``v2`` branch : this is the branch for a revamp of wallabag.
21 A whole chapter is to be focused on it.
22
23Workflow
24--------
25
26All the rules for contributing to the git repository are in the
27`CONTRIBUTING.md file of
28wallabag <https://github.com/wallabag/wallabag/blob/master/CONTRIBUTING.md>`__.
29Please read carefully this file before you make any change.
diff --git a/docs/en/Developer/write_config_files.rst b/docs/en/Developer/write_config_files.rst
new file mode 100644
index 00000000..c1ea61df
--- /dev/null
+++ b/docs/en/Developer/write_config_files.rst
@@ -0,0 +1,52 @@
1Write config files
2==================
3
4wallabag can use specific site config files to parse website articles.
5These files are stored in the
6```inc/3rdparty/site_config/standard`` <https://github.com/wallabag/wallabag/tree/master/inc/3rdparty/site_config/standard>`__
7folder.
8
9The format used for these files is
10`XPath <http://www.w3.org/TR/xpath20/>`__. Look at some examples in the
11folder.
12
13Automatic config files generation
14---------------------------------
15
16Fivefilters has created a `very useful
17tool <http://siteconfig.fivefilters.org/>`__ to create config files. You
18just type in the adress of the article to work on with, and you select
19the area containing the content you want.
20
21.. figure:: https://lut.im/RNaO7gGe/l9vRnO1b
22 :alt: siteconfig
23
24 siteconfig
25| You should confirm this area by trying with other articles.
26| When you got the right area, just click on *Download Full-Text RSS
27site config* to download your file.
28
29Manual config file generation
30-----------------------------
31
32If Fivefilters tool doesn't work correctly, take a look at the source
33(Ctrl + U on Firefox and Chromium). Search for your content and get the
34``class`` or the ``id`` attribute of the area containing what you want.
35
36Once you've got the id or class, you can write for example one or
37another of these lines:
38
39::
40
41 body: //div[@class='myclass']
42 body: //div[@id='myid']
43
44Then, test you file. If you got the right content but you want to strip
45unnecessary parts, do:
46
47::
48
49 strip: //div[@class='hidden']
50
51You can look at other options for siteconfig files
52`here <http://help.fivefilters.org/customer/portal/articles/223153-site-patterns>`__.
diff --git a/docs/en/User/configure_wallabag.rst b/docs/en/User/configure_wallabag.rst
new file mode 100644
index 00000000..7a0bc95f
--- /dev/null
+++ b/docs/en/User/configure_wallabag.rst
@@ -0,0 +1,118 @@
1.. _`Configure wallabag`:
2
3Configure wallabag
4==================
5
6From the configuration menu, you can change some of wallabag's options.
7
8Some parts won't be detailed here, as they have a dedicated chapter in
9the documentation (:ref:`RSS feeds`, :ref:`Import / Export`, :ref:`ePub conversion` and :ref:`Multi users`).
10
11Saving articles
12---------------
13
14You'll find help about the different ways to save articles to your
15wallabag here.
16
17Save article field
18~~~~~~~~~~~~~~~~~~
19
20Enter a link in the field and click “bag it!” to save.
21
22Browser extensions
23~~~~~~~~~~~~~~~~~~
24
25Links to download extensions for your favourite browser, Firefox or
26Chrome.
27
28Mobile apps
29~~~~~~~~~~~
30
31Links to download mobile apps, Android, iOS or Windows Phone.
32
33For Android, you have the choice to download either from Google's Play
34Store of from the Free and Open Source market
35`F-Droid <https://f-droid.org>`__
36
37Bookmarklet
38~~~~~~~~~~~
39
40Lastly, you can use the bookmarklet. A bookmarklet is a simple link you
41can drag to your browser's bookmarks. Once it's in your bookmarks,
42simply clicking on it will save the webpage you're currently viewing to
43your wallabag.
44
45Feeds
46-----
47
48Plese refer to `RSS feeds <rss_feed.html>`__ for more details.
49
50.. _`Howto change theme`:
51
52Theme
53-----
54
55As they say, “all tastes and colors are found in nature”. That's why
56wallabag allows you to change its appearance through the use of themes,
57in order to please everyone.
58
59Select the theme of your choice from the drop down list and confirm by
60clicking on **Update**.
61
62Language
63--------
64
65Select the language of your choice in the drop down list and confirm by
66clicking on **Update**.
67
68Import
69------
70
71Please refer to `Import/Export <import_export.html>`__ for more details.
72
73Export
74------
75
76Please refer to `Import/Export <import_export.html>`__ for more details.
77
78Clear the cache
79---------------
80
81The cache allows wallabag perform certain functions faster.
82
83After updating wallabag, it is advised to clear the cache.
84
85Click on “delete cache” to do so (no confirmation will be asked).
86
87Password
88--------
89
90Fill in your new password in the two dedicated fields and confirm by
91clicking on **Update**.
92
93You will be disconnected and will have to enter your new password to
94access your wallabag.
95
96User
97----
98
99Add a user here by entering their name, password and (optionnaly) email
100in the corresponding fields.
101
102You may not be able to add a user if don't have the rights to do so.
103
104Remind newly created users to change their password the first time they
105connect to wallabag!
106
107Delete
108------
109
110Delete your user account on wallabag here.
111
112If there is only one account, you won't be able to delete the account.
113
114Upgrade
115-------
116
117Wallabag will check its curent version and if there is a new version
118available and display this information here.
diff --git a/docs/en/User/epub_conversion.rst b/docs/en/User/epub_conversion.rst
new file mode 100644
index 00000000..7b31fe07
--- /dev/null
+++ b/docs/en/User/epub_conversion.rst
@@ -0,0 +1,32 @@
1.. _`ePub conversion`:
2
3ePub conversion
4===============
5
6To enable you to read your articles on a e-reader, wallabag can convert
7them to the ePub format, and hence create an eBook for your long winter
8evenings.
9
10A word of caution
11-----------------
12
13Be careful, the creation of ePub files can be very resource demanding
14for the server on which wallabag is installed. It depends on the number
15of articles and on their length. Do not create a really big eBook if
16this is not necessary.
17
18Where to convert the articles
19-----------------------------
20
21You can convert your articles at various places in wallabag:
22
23- on the reading page of an article: the ePub link will convert this
24 article only
25- from the list of articles (unread, favorite or archived articles,
26 articles with a tag): a link at the bottom of the page allows you to
27 convert all the article of this category
28- from a search: the link is at the bottom of the page
29- from the configuration page: you can convert all your articles,
30 whatever the category to which they belong
31
32TODO talk about calibre
diff --git a/docs/en/User/framabag_account_creation.rst b/docs/en/User/framabag_account_creation.rst
new file mode 100644
index 00000000..bce8cdfd
--- /dev/null
+++ b/docs/en/User/framabag_account_creation.rst
@@ -0,0 +1,49 @@
1.. _`Framabag account creation`:
2
3Framabag account creation
4=========================
5
6If you do not want to install and update wallabag, or if you do not have
7the know-how to install it, it is possible to create an account for free
8at `Framabag.org <https://www.framabag.org>`__.
9
10Account creation
11----------------
12
13Click on the button **Créez votre compte / Create your account**.
14
15You have to input some information: your username, your password and
16your email address. Your address is used only to validate your account,
17except if you check the box to subscribe the newsletter (3 to 4 messages
18per year).
19
20Once this form validated, you will receive an email with the
21confirmation link. Click on it to create your account.
22
23You will receive a last email with the address of your Framabag account,
24which will look like ``https://www.framabag.org/u/Your-username``.
25
26Information storage
27-------------------
28
29Framabag use one database per user. We do not and will not use your
30stored data.
31
32You have forgotten your password
33--------------------------------
34
35| If you have forgotten your password to get connected to Framabag, a
36form is available `on the main page of the
37service <https://www.framabag.org>`__.
38| Fill it, and a confirmation will be sent to you and will allow you to
39input a new password.
40
41Account deletion
42----------------
43
44If you wish to delete your account, contact us by email:
45hello@wallabag.org using the address your created your account with, and
46state your username.
47
48We will answer you after your account has been deleted: then, no
49information about you will be stored by Framabag.
diff --git a/docs/en/User/import_export.rst b/docs/en/User/import_export.rst
new file mode 100644
index 00000000..8cd18bf2
--- /dev/null
+++ b/docs/en/User/import_export.rst
@@ -0,0 +1,107 @@
1.. _`Import / Export`:
2
3Import and export data
4======================
5
6Import
7------
8
9To import data in wallabag, go to the page **Configuration**.
10
11Caution
12~~~~~~~
13
14Data import can be a **demanding process** for your server. Hence, it is
15done in two steps:
16
17- Insertion of the URL in the wallabag database
18- in the second step, the retrieval, for each article, of its full
19 content.
20
21These two steps cannot be done concurrently, because it let us the
22possibility to import thousands of links, but today, wallabag does not
23have sufficient technical capabilities to do this task automatically.
24
25From Pocket
26~~~~~~~~~~~
27
28Export your data from Pocket
29^^^^^^^^^^^^^^^^^^^^^^^^^^^^
30
31From your Pocket account, go to the options. TODO
32
33Import your Pocket data
34^^^^^^^^^^^^^^^^^^^^^^^
35
36From the configuration page of wallabag, section **Import**, select the
37file ``ril_export.html`` generated by Pocket, then click on **Import**.
38Wallabag only insert these links in the database. Now, you have to get
39the content of each article.
40
41For this, click on ``Click to finish import``: wallabag will fetch the
42content of 10 articles at a time.
43
44TODO
45
46TODO new ticket: why when a click is done, this does not load in a loop?
47I believe this was doing this ping @mariroz
48
49From Instapaper
50~~~~~~~~~~~~~~~
51
52Export your data from Instapaper
53^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
54
55TODO
56
57Import your Instapaper data
58^^^^^^^^^^^^^^^^^^^^^^^^^^^
59
60TODO
61
62From Readability
63~~~~~~~~~~~~~~~~
64
65Export your data from Readability
66^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
67
68TODO
69
70Import your Readability data
71^^^^^^^^^^^^^^^^^^^^^^^^^^^^
72
73TODO
74
75From wallabag
76~~~~~~~~~~~~~
77
78Since you can export your data from wallabag (see below), it is of
79course possible to re-import them.
80
81In the import form, select your wallabag-exported file (format JSON).
82Start the import, et voilà.
83
84Unlike the above imports, this process is shorter because all the data
85(title and content of the articles) are already included in the file.
86Hence wallabag does not have to access each URL. However, the import
87file is necessarily bigger.
88
89From a HTML or JSON file
90~~~~~~~~~~~~~~~~~~~~~~~~
91
92TODO
93
94Export
95------
96
97It is possible to export your data from the page **Configuration** of
98wallabag. Several reasons to do this:
99
100- re-install of wallabag
101- leave the Framabag service to install your own wallabag
102- a user with an account on a multi-user wallabag want to have his/her
103 own wallabag installation
104- ...
105
106This will lead you to download a file `at the JSON
107format <http://en.wikipedia.org/wiki/JavaScript_Object_Notation>`__. As detailed above, you can import this file in wallabag.
diff --git a/docs/en/User/issue_with_article.rst b/docs/en/User/issue_with_article.rst
new file mode 100644
index 00000000..408403f2
--- /dev/null
+++ b/docs/en/User/issue_with_article.rst
@@ -0,0 +1,36 @@
1.. _`Article is not displayed properly`:
2
3My article is not displayed properly in wallabag
4================================================
5
6If you think wallabag do not copy well the content of an article (empty
7or incomplete text), here are some suggestions.
8
9Ask for help
10------------
11
12Via an email or a ticket, do not forget to give some information that
13are important for us to better solve the problem:
14
15- The URL of the article
16- What wallabag displays
17- What you were expecting
18- The wallabag version of if you use Framabag
19
20Open a ticket on github
21~~~~~~~~~~~~~~~~~~~~~~~
22
23To open a new ticket, you should `go to
24github <https://github.com/wallabag/wallabag/issues/new>`__. An account
25is required. Do not forget to send us the information listed above.
26
27Send us an email
28~~~~~~~~~~~~~~~~
29
30Send us the link in a email to the address
31`hello@wallabag.org <mailto:hello@wallabag.org?subject=Wrong%20display%20in%20wallabag>`__. Do not forget to send us the information listed above.
32
33Solve this display problem
34--------------------------
35
36TODO
diff --git a/docs/en/User/organize_articles.rst b/docs/en/User/organize_articles.rst
new file mode 100644
index 00000000..734e4de6
--- /dev/null
+++ b/docs/en/User/organize_articles.rst
@@ -0,0 +1,109 @@
1.. _`Organize articles`:
2
3Organize articles
4=================
5
6To be able to find more easily your articles, several methods are
7available.
8
9Tags
10----
11
12Assign a tag
13~~~~~~~~~~~~
14
15When saving an article
16^^^^^^^^^^^^^^^^^^^^^^
17
18To tag an article when saving it, just click on the tag icon next to the
19URL field before hitting the Save button. At the moment, it is possible
20only to do this from the web interface, but it could come to some apps
21or extensions.
22
23From the article
24^^^^^^^^^^^^^^^^
25
26To tag an already-saved article, go to the reading page of the article.
27There is a part ``tags`` followed with a pencil. Click on the pencil.
28
29Input in the box the tags you want to assign. Add as many tags as you
30want. They need to be separated by commas and not spaces.
31Auto-completion is available here: when you type the first letters of an
32existing tag, it is not necessary to type the whole word. Select it in
33the drop-down list. Once all your tags are inputted, click on the button
34**Tag**.
35
36Then, you can go back to your article and read it.
37
38From the search
39^^^^^^^^^^^^^^^
40
41A full chapter on search is available. Here, we will describe only how
42to assign a tag from your search.
43
44When your search displays results, there is a link
45``Apply the tag ABCD to this search`` at the bottom of the page. Click
46on it: a tad depending on your search (here ``ABCD``) will be assigned
47to all the articles found.
48
49Find all the articles with a given tag
50~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
51
52In the wallabag menu, click on **Tags**. Then, all the tags you have
53created are displayed, sorted by the number of articles for each tag.
54Click on one of these tags to find all the articles with this tag.
55
56Preferred articles
57------------------
58
59When you wish to set aside an article, you can mark it as preferred.
60
61Set an article as favorite
62~~~~~~~~~~~~~~~~~~~~~~~~~~
63
64From the reading page of an article, or from a list of articles (such as
65the list of unread articles), you can set an article as favorite simply
66by a click on the star which is displayed. Click again on the star will
67remove the **favorite** status of this article.
68
69Find all the favorite articles
70~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71
72In the wallabag menu, click on **Favorites** to display the list of all
73the articles that you have set as favorite.
74
75Archived articles
76-----------------
77
78When you have read an article, you can archive it: hence it will not be
79displayed in your list of unread articles.
80
81Archiving an article does not remove it from wallabag.
82
83Archive an article
84~~~~~~~~~~~~~~~~~~
85
86| From the reading page of an article, or from a list of articles (such
87as the list of unread articles), you can archive an article simply by
88clicking on the icon ✓.
89| Click again on this icon will set back the **unread** status of the
90article.
91
92Find all the archived articles
93~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
94
95In the wallabag menu, click on **Archive** to find all the articles that
96you have archived.
97
98Delete an article
99-----------------
100
101Be cautious: the deletion of an article is **definitive**. It is deleted
102from the wallabag database.
103
104To delete an article, a trash icon is displayed on the page of an
105article or of a list of articles (unread articles, favorites or
106archived, for example).
107
108We trust you: that is why there is no confirmation message during the
109deletion.
diff --git a/docs/en/User/read_an_article.rst b/docs/en/User/read_an_article.rst
new file mode 100644
index 00000000..6eef46f8
--- /dev/null
+++ b/docs/en/User/read_an_article.rst
@@ -0,0 +1,63 @@
1Read an article
2===============
3
4Reading an article is not difficult in wallabag: you only have to click on the title of the article for it to be displayed.
5
6Back to where you left the article
7----------------------------------
8
9If you stop reading an article halfway through, the next time wallabag will open it right where you left off.
10
11This feature only works with web applications and not with smartphone applications.
12
13Possible actions in an article
14------------------------------
15
16The following actions can be performed through the icons displayed at the top of the page. We assume here that you are using the Baggy theme (see the section on :ref:`Howto change theme`). Icons in other themes are very similar.
17
18Here are the actions, in the order of appearance of the icons.
19
20Read the original article
21~~~~~~~~~~~~~~~~~~~~~~~~~
22
23Open the article on its original location.
24
25Mark the article as read
26~~~~~~~~~~~~~~~~~~~~~~~~
27
28Archive the article, which will be placed into the **Archive** category of the wallabag menu. Clicking again on this button will move the article back to the **unread** category.
29
30Mark the article as favorite
31~~~~~~~~~~~~~~~~~~~~~~~~~~~~
32
33Mark the article as favorite, and it will be placed into the **Favorites** category of the wallabag menu. Clicking again on this button will remove the favorite status.
34
35Delete the article
36~~~~~~~~~~~~~~~~~~
37
38Delete the article from wallabag permanently. It cannot be restored. Be careful: no confirmation message is displayed.
39
40Share through twitter
41~~~~~~~~~~~~~~~~~~~~~
42
43Share the title and the original link of the article on twitter.
44
45Share via email
46~~~~~~~~~~~~~~~
47
48Share the title and the original link of the article via e-mail.
49
50Print the article
51~~~~~~~~~~~~~~~~~
52
53Open the print window of the browser.
54
55Convert into ePub
56~~~~~~~~~~~~~~~~~
57
58Convert the article into ePub format: see the section on :ref:`ePub conversion`.
59
60Notify us that the article appears wrong
61~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
62
63Notify the wallabag developers that an article is not displayed as expected (see the section on :ref:`Article is not displayed properly`).
diff --git a/docs/en/User/rss_feed.rst b/docs/en/User/rss_feed.rst
new file mode 100644
index 00000000..760c2856
--- /dev/null
+++ b/docs/en/User/rss_feed.rst
@@ -0,0 +1,41 @@
1.. _`RSS feeds`:
2
3RSS feeds
4=========
5
6The RSS feeds allow you to:
7
8- read your articles from your favorite RSS feed reader.
9- to activate the reading features for smartphone softwares
10
11| First, you must activate the RSS feature by generating a feed token.
12| Go to **config** in wallabag and generate a token in the section
13**Feeds**. You can generate a new token at any time.
14
15Read articles
16-------------
17
18Once the token created, you have access to three RSS feeds:
19
20- the one of the unread articles
21- the one of the favorites articles
22- the one of the archived articles
23
24Add the feed you want to your RSS feed reader. Be careful: when you will
25be reading an article from your feed reader, this will not set it as
26read in wallabag.
27
28Share your readings
29~~~~~~~~~~~~~~~~~~~
30
31If you wish to share your readings with somebody, send him for example
32the RSS feed of your favorite articles. Hence, as soon as an article
33will be set as favorite in wallabag, this person will be able to read it
34too.
35
36Activate the features for smartphones
37-------------------------------------
38
39You ave created an RSS feed token. It will also be useful to you to
40configure your smartphone software. For more information about
41smartphone sofwares, you can read :ref:`Save your first article`.
diff --git a/docs/en/User/save_your_first_article.rst b/docs/en/User/save_your_first_article.rst
new file mode 100644
index 00000000..e6e884a3
--- /dev/null
+++ b/docs/en/User/save_your_first_article.rst
@@ -0,0 +1,226 @@
1.. _`Save your first article`:
2
3Save your first article
4=======================
5
6Once connected on wallabag, you have many ways to save an article.
7
8From the web application
9------------------------
10
11Let’s see first how to do from the web application. In the menu, you
12have a link **save a link**. Clicking on it, a form shows up: you simply
13have to type the web adress of the article you want to save.
14
15Confirm to store the content of the article.
16
17By default, only the text is saved. If you want to store a copy of the
18images on your server, you have to enable the setting
19*DOWNLOAD\_PICTURES*. Read the chapter on hidden options for more
20information.
21
22From the bookmarklet
23--------------------
24
25From `Wikipedia’s definition`_
26
27 A bookmarklet is a `bookmark`_ stored in a `web browser`_ that
28 contains `JavaScript`_\ commands to extend the browser’s
29 functionality.
30
31 Bookmarklets are unobtrusive scripts stored as the URL of a bookmark
32 in a web browser or as a hyperlink on a web page.
33
34 When clicked, a bookmarklet performs some function, one of a wide
35 variety such as a search query or data extraction. Bookmarklets are
36 usually `JavaScript programs`_.
37
38From the wallabag’s menu, click on **settings**. On the first part of
39this page, we have listed all the ways to save an article. You’ll find
40the bookmarklet (it’s the ``Bag it!`` link) to drag and drop in the
41bookmarks bar of your web browser. From now on, when you want to save
42the article you are browsing, you just have to click on this bookmarklet
43and the article will be automatically saved.
44
45From your smartphone
46--------------------
47
48Above all else
49~~~~~~~~~~~~~~
50
51To use a smartphone application, you have to enable RSS feeds from the
52settings panel of wallabag. Then some information will be displayed,
53like your security token. Read the chapter on RSS feeds for more
54information.
55
56Android
57~~~~~~~
58
59Installation and configuration
60^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
61
62You can download the android application from the `Google Play Store`_
63and from `F-droid`_. It’s the exact same application on those two
64stores.
65
66Once installed, start the application, go to the **settings** part et
67fill in the **URL (complete address of your wallabag installation or
68your Framabag account)** and **User ID (in most cases, you’ll have to
69put 1)** fields. If you have created multiple accounts from wallabag,
70you will have to to fill the user account you want to connect to your
71application and your security **Token** (enter properly all the token’s
72letters as seen in the settings part of wallabag).
73
74Saving of an article
75^^^^^^^^^^^^^^^^^^^^
76
77Now that everything is correctly set up, as soon as you browse on your
78smartphone’s web browser, you can share an article in wallabag at any
79time from the **Share** menu: you’ll find a **Bag it!** entry which will
80add your article in wallabag.
81
82Reading
83^^^^^^^
84
85When you open the application, click on Synchronize: your recently saved
86articles will be downloaded on your smartphone.
87
88You don’t need an internet connection anymore: click on **List
89articles** to start your reading.
90
91At the end of each article, a **Mark as read** button allows you to
92archive the article.
93
94To date, the synchronisation occurs in one direction (from wallabag to
95the application), thus preventing mark as read an article on wallabag
96from your smartphone.
97
98iOS
99~~~
100
101Installation and configuration
102^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
103
104You can download the iOS application from the `AppStore`_.
105
106Once installed, configure the app by filling following fields inside the
107settings: the **URL (complete address of your wallabag installation or
108your Framabag account)** and **User ID (in most cases, you’ll have to
109put 1)** field. If you have created multiple accounts from wallabag, you
110will have to to fill the user account you want to connect to your
111application and your security **Token** (enter properly all the token’s
112letters as seen in the settings part of wallabag).
113
114Usage
115^^^^^
116
117If the app is configured correctly, the app will automatically download
118the articles from your wallabag (use **pull-to-refresh** to trigger this
119update manually). Once an article is downloaded, it’ll be available
120offline from your app.
121
122Unfortunately you can only locally mark an article as read (it will not
123synchronise to your online wallabag).
124
125Saving articles
126~~~~~~~~~~~~~~~
127
128If you’re browsing a website and want to add the current article to your
129wallabag, simply tap the **Share**-button and select **Bag it!** (if you
130don’t find the wallabag icon, have a look in the **more**-menu). If
131everything is set up correctly, your article will be saved (you may have
132to login from time to time).
133
134Windows Phone
135~~~~~~~~~~~~~
136
137Installation and configuration
138^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
139
140You can download the Windows Phone application from the `Windows Store`_
141or directly from your smartphone’s Store.
142
143Once installed, the application will show you a notification on the
144first launch, asking the configuration of your wallabag server. Go to
145the **Settings** part of the application by pressing the three dots menu
146at the bottom of the screen, then fill in the **URL (complete address of
147your wallabag installation or your Framabag account)** and **User ID (in
148most cases, you’ll have to put 1)** fields.
149
150If you have created multiple accounts from wallabag, you will have to to
151fill the user account you want to connect to your application and your
152security **Token** (enter properly all the token’s letters as seen in
153the setting part of wallabag).
154
155From your web browser
156---------------------
157
158Firefox Classic Add-on
159~~~~~~~~~~~~~~~~~~~~~~
160
161Download the Firefox add-on at `addons.mozilla.org`_ and install it like
162any other Firefox add-on.
163
164In the add-on’s settings, fill the complete URL of your installation of
165wallabag or your Framabag account.
166
167Personalize the Firefox toolbar to add wallabag (**W** icon). When you
168find an article you want to save, click on this icon: a new window will
169open to add the article and will close itself automatically.
170
171Firefox Social API Service
172~~~~~~~~~~~~~~~~~~~~~~~~~~
173
174*Available from wallabag v1.9.1 only*
175
176You will need an https connection to use this. It’s a Firefox
177`requirement`_, sorry.
178
179With Firefox 29+ versions, your browser comes with an integrated
180interface to share things to multiple social services directly from your
181browser. In the Firefox interface, it is shown a paper plane-like icon
182that you will use to share a page, which means here, save an article.
183You can add the service by going into the Config page of wallabag, then
184click on Mozilla Services Social API Extension. You must also accept to
185use Firefox Services.
186
187Chrome
188~~~~~~
189
190Download the Chrome add-on `on the dedicated website`_ and install it
191like any other Chrome add-on.
192
193In the add-on’s settings, fill the complete URL of your installation of
194wallabag or your Framabag account.
195
196During the addon’s installation, a new icon appear in Chrome toolbar (a
197**W** icon). When you find an article you want to save, click on this
198icon: a popup will appear to confirm that your article has been saved.
199
200Opera
201~~~~~
202
203The recent versions of Opera (15+) allow to install add-ons compatible
204with Chrome.
205
206First, install the add-on named `Download Chrome Extensions`_ which will
207allow you to install add-ons from the Chrome Web Store. Then, go `to to
208Google site`_ and get the Chrome add-on by clicking on *Add to Opera*. A
209message will invite you to confirm this action because this add-on is
210not coming from a certified source. The behavior will be the same as for
211Chrome (see above).
212
213.. _Wikipedia’s definition: http://fr.wikipedia.org/wiki/Bookmarklet
214.. _bookmark: http://en.wikipedia.org/wiki/Internet_bookmark
215.. _web browser: http://en.wikipedia.org/wiki/Web_browser
216.. _JavaScript: http://en.wikipedia.org/wiki/JavaScript
217.. _JavaScript programs: http://en.wikipedia.org/wiki/Computer_program
218.. _Google Play Store: https://play.google.com/store/apps/details?id=fr.gaulupeau.apps.InThePoche
219.. _F-droid: https://f-droid.org/app/fr.gaulupeau.apps.InThePoche
220.. _AppStore: https://itunes.apple.com/app/id828331015
221.. _Windows Store: https://www.microsoft.com/en-us/store/apps/wallabag/9nblggh11646
222.. _addons.mozilla.org: https://addons.mozilla.org/firefox/addon/wallabag/
223.. _requirement: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Social_API/Manifest#Manifest_Contents
224.. _on the dedicated website: https://chrome.google.com/webstore/detail/wallabag/bepdcjnnkglfjehplaogpoonpffbdcdj
225.. _Download Chrome Extensions: https://addons.opera.com/en/extensions/details/download-chrome-extension-9/
226.. _to to Google site: https://chrome.google.com/webstore/detail/wallabag/bepdcjnnkglfjehplaogpoonpffbdcdj
diff --git a/docs/en/User/search.rst b/docs/en/User/search.rst
new file mode 100644
index 00000000..d2bda8bc
--- /dev/null
+++ b/docs/en/User/search.rst
@@ -0,0 +1,21 @@
1Search content in wallabag
2==========================
3
4To enable you to find an article quickly, we set up a full search
5engine.
6
7Click on **Search** in the wallabag menu. Then, enter your search terms.
8
9Wallabag will go through all your articles, and lists the ones
10containing the search terms in their title, their content or their URL.
11
12Convert this search into ePub format
13------------------------------------
14
15You can convert the listed articles to the ePub format, so that you can
16read them in your e-reader, for example. Look at :ref:`ePub conversion` for more about this.
17
18Assign a tag to your search results
19-----------------------------------
20
21You can create a tag based on your search criteria. Loot at :ref:`Organize articles` for more about this.
diff --git a/docs/en/conf.py b/docs/en/conf.py
new file mode 100644
index 00000000..ae879a61
--- /dev/null
+++ b/docs/en/conf.py
@@ -0,0 +1,87 @@
1# -*- coding: utf-8 -*-
2#
3# wallabag documentation build configuration file, created by
4# sphinx-quickstart on Fri Oct 16 06:47:23 2015.
5
6import sys
7import os
8
9extensions = []
10templates_path = ['_templates']
11source_suffix = '.rst'
12master_doc = 'index'
13project = u'wallabag'
14copyright = u'2013-2015, Nicolas Lœuillet - MIT Licence'
15version = '2.0.0'
16release = version
17exclude_patterns = ['_build']
18pygments_style = 'sphinx'
19html_theme = 'default'
20html_static_path = ['_static']
21htmlhelp_basename = 'wallabagdoc'
22latex_elements = {
23
24}
25
26latex_documents = [
27 ('index', 'wallabag.tex', u'wallabag Documentation',
28 u'Nicolas Lœuillet', 'manual'),
29]
30
31man_pages = [
32 ('index', 'wallabag', u'wallabag Documentation',
33 [u'Nicolas Lœuillet'], 1)
34]
35
36texinfo_documents = [
37 ('index', 'wallabag', u'wallabag Documentation',
38 u'Nicolas Lœuillet', 'wallabag', 'One line description of project.',
39 'Miscellaneous'),
40]
41
42##### Guzzle sphinx theme
43
44import guzzle_sphinx_theme
45html_translator_class = 'guzzle_sphinx_theme.HTMLTranslator'
46html_theme_path = guzzle_sphinx_theme.html_theme_path()
47html_theme = 'guzzle_sphinx_theme'
48
49# Custom sidebar templates, maps document names to template names.
50html_sidebars = {
51 '**': ['logo-text.html', 'globaltoc.html', 'searchbox.html']
52}
53
54# Register the theme as an extension to generate a sitemap.xml
55extensions.append("guzzle_sphinx_theme")
56
57# Guzzle theme options (see theme.conf for more information)
58html_theme_options = {
59
60 # Set the path to a special layout to include for the homepage
61 # "index_template": "homepage.html",
62
63 # Allow a separate homepage from the master_doc
64 # homepage = index
65
66 # Set the name of the project to appear in the nav menu
67 # "project_nav_name": "Guzzle",
68
69 # Set your Disqus short name to enable comments
70 # "disqus_comments_shortname": "my_disqus_comments_short_name",
71
72 # Set you GA account ID to enable tracking
73 # "google_analytics_account": "my_ga_account",
74
75 # Path to a touch icon
76 # "touch_icon": "",
77
78 # Specify a base_url used to generate sitemap.xml links. If not
79 # specified, then no sitemap will be built.
80 #"base_url": "http://guzzlephp.org"
81
82 # Allow the "Table of Contents" page to be defined separately from "master_doc"
83 # tocpage = Contents
84
85 # Allow the project link to be overriden to a custom URL.
86 # projectlink = http://myproject.url
87}
diff --git a/docs/en/index.rst b/docs/en/index.rst
new file mode 100644
index 00000000..6ccfd44c
--- /dev/null
+++ b/docs/en/index.rst
@@ -0,0 +1,57 @@
1wallabag documentation
2======================
3
4.. image:: ../img/wallabag.png
5 :alt: wallabag logo
6 :align: center
7
8**wallabag** is a read-it-later application: it saves a web page by
9keeping content only. Elements like navigation or ads are deleted.
10
11The main documentation for the site is organized into a couple sections:
12
13* :ref:`user-docs`
14* :ref:`admin-docs`
15* :ref:`dev-docs`
16
17.. _user-docs:
18
19.. toctree::
20 :maxdepth: 2
21 :caption: User Documentation
22
23 user/create_account
24 user/login
25 user/configuration
26 user/first_article
27
28user/organize
29user/filters
30User/read_an_article
31User/search
32User/epub_conversion
33User/issue_with_article
34User/rss_feed
35User/import_export
36
37.. _admin-docs:
38
39.. toctree::
40 :maxdepth: 2
41 :caption: Admin Documentation
42
43 Administrator/install
44 Administrator/update
45 Administrator/hidden_options
46 Administrator/multiusers
47 Administrator/sessions
48
49.. _dev-docs:
50
51.. toctree::
52 :maxdepth: 2
53 :caption: Developer Documentation
54
55 Developer/write_config_files
56 Developer/create_new_theme
57 Developer/git_repo
diff --git a/docs/en/requirements.txt b/docs/en/requirements.txt
new file mode 100644
index 00000000..06fc8973
--- /dev/null
+++ b/docs/en/requirements.txt
@@ -0,0 +1,2 @@
1Sphinx>=1.3.0,<1.4.0
2guzzle_sphinx_theme>=0.7.0,<0.8.0
diff --git a/docs/en/user/configuration.rst b/docs/en/user/configuration.rst
new file mode 100644
index 00000000..60aae4e5
--- /dev/null
+++ b/docs/en/user/configuration.rst
@@ -0,0 +1,61 @@
1Configuration
2=============
3
4Now you're logged in, it's time to configure your account as you want.
5
6Click on ``Config`` menu. You have four tabs: ``Settings``, ``RSS``, ``User information`` and ``Password``.
7
8Settings
9--------
10
11Theme
12~~~~~
13
14wallabag is customizable. You can choose your prefered theme here. You can also create a new one, a chapter is dedicated for this. The default theme is ``Material``, it's the theme used in the documentation screenshots.
15
16Items per page
17~~~~~~~~~~~~~~
18
19You can change the number of articles displayed on each page.
20
21Language
22~~~~~~~~
23
24You can change the language of wallabag interface.
25
26RSS
27---
28
29wallabag provides RSS feeds for each article status: unread, starred and archive.
30
31Firstly, you need to create a personal token: click on ``Create your token``.
32It's possible to change your token by clicking on ``Reset your token``.
33
34Now you have three links, one for each status: add them into your favourite RSS reader.
35
36You can also define how many articles you want in each RSS feed (default value: 50).
37
38User information
39----------------
40
41You can change your name, your email address and enable ``Two factor authentication``.
42
43Two factor authentication
44~~~~~~~~~~~~~~~~~~~~~~~~~
45
46 Two-factor authentication (also known as 2FA) is a technology patented in 1984 that provides identification of users by means of the combination of two different components.
47
48https://en.wikipedia.org/wiki/Two-factor_authentication
49
50If you enable 2FA, each time you want to login to wallabag, you'll receive a code by email. You have to put this code on the following form.
51
52.. image:: ../../img/user/2FA_form.png
53 :alt: Two factor authentication
54 :align: center
55
56If you don't want to receive a code each time you want to login, you can check the ``I'm on a trusted computer`` checkbox: wallabag will remember you for 15 days.
57
58Password
59--------
60
61You can change your password here.
diff --git a/docs/en/user/create_account.rst b/docs/en/user/create_account.rst
new file mode 100644
index 00000000..11fe304c
--- /dev/null
+++ b/docs/en/user/create_account.rst
@@ -0,0 +1,43 @@
1Create an account
2=================
3
4On the login page, click on ``Register`` button.
5
6.. image:: ../../img/user/registration_form.png
7 :alt: Registration form
8 :align: center
9
10You have to fill the form. Please sure to type a valid email address, we'll send you an activation email.
11
12.. image:: ../../img/user/sent_email.png
13 :alt: Email was sent to activate account
14 :align: center
15
16Check your inbox, you now have a new mail with a link like this ``http://wallabag/register/confirm/Ba19wokGovN-DdBQNfg4YgRkUQWRP4-k2g0Bk-hBTX4``. Click on it to activate your account.
17
18Your account is now activated.
19
20.. image:: ../../img/user/activated_account.png
21 :alt: Welcome on board!
22 :align: center
23
24Frequently asked questions
25--------------------------
26
27I can't valid the registration form
28~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
29
30Make sure that all fields are well filled:
31
32* valid email address
33* same passwords in two fields
34
35I don't receive my activation email
36~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
37
38Are you sure your email address was correct? Did you check your spams folder?
39
40When I click on the activation link, I've got this message: ``The user with confirmation token "DtrOPfbQeVkWf6N" does not exist``.
41~~~~~~~~~~~~~~~
42
43You already enabled your account or the URL of the activation email is wrong.
diff --git a/docs/en/user/first_article.rst b/docs/en/user/first_article.rst
new file mode 100644
index 00000000..4e6735c6
--- /dev/null
+++ b/docs/en/user/first_article.rst
@@ -0,0 +1,79 @@
1Save your first article
2=======================
3
4The main purpose of wallabag is to save web articles. You have many ways to do it.
5
6By using a bookmarklet
7----------------------
8
9On the ``Howto`` page, you have a ``Bookmarklet`` tab. Drag and drop the ``bag it!`` link to your bookmarks bar of your browser.
10
11Now, each time you're reading an article on the web and you want to save it, click on the ``bag it!`` link in your bookmarks bar. The article is saved.
12
13By using the classic form
14-------------------------
15
16In the top bar of your screen, you have 3 icons. With the first one, a plus sign, you can easily save a new article.
17
18.. image:: ../../img/user/topbar.png
19 :alt: Top bar
20 :align: center
21
22Click on it to display a new field, paste the article URL inside and press your ``Return`` key. The article is saved.
23
24By using a browser add-on
25-------------------------
26
27Firefox
28~~~~~~~
29
30Firefox Classic Add-on
31^^^^^^^^^^^^^^^^^^^^^^
32
33Download the Firefox add-on at `addons.mozilla.org`_ and install it like
34any other Firefox add-on.
35
36In the add-on’s settings, fill the complete URL of your installation of
37wallabag or your Framabag account.
38
39Personalize the Firefox toolbar to add wallabag (**W** icon). When you
40find an article you want to save, click on this icon: a new window will
41open to add the article and will close itself automatically.
42
43Firefox Social API Service
44^^^^^^^^^^^^^^^^^^^^^^^^^^
45
46*Available from wallabag v1.9.1 only*
47
48You will need an https connection to use this. It’s a Firefox
49`requirement`_, sorry.
50
51With Firefox 29+ versions, your browser comes with an integrated
52interface to share things to multiple social services directly from your
53browser. In the Firefox interface, it is shown a paper plane-like icon
54that you will use to share a page, which means here, save an article.
55You can add the service by going into the Config page of wallabag, then
56click on Mozilla Services Social API Extension. You must also accept to
57use Firefox Services.
58
59Chrome
60~~~~~~
61
62By using your smarphone application
63-----------------------------------
64
65Android
66~~~~~~~
67
68Firefox OS
69~~~~~~~~~~
70
71Windows Phone
72~~~~~~~~~~~~~
73
74iOS
75~~~
76
77
78.. _addons.mozilla.org: https://addons.mozilla.org/firefox/addon/wallabag/
79.. _requirement: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Social_API/Manifest#Manifest_Contents
diff --git a/docs/en/user/login.rst b/docs/en/user/login.rst
new file mode 100644
index 00000000..1b6b8875
--- /dev/null
+++ b/docs/en/user/login.rst
@@ -0,0 +1,20 @@
1Login
2=====
3
4Your account is now enabled, congratulations!
5
6To login to wallabag, fill the form on login page.
7
8If you are on your personal computer and you want to stay connected, you can check the ``Keep me logged in`` checkbox: wallabag will remember you for one year.
9
10.. image:: ../../img/user/login_form.png
11 :alt: Login form
12 :align: center
13
14Frequently asked questions
15--------------------------
16
17I forgot my password
18~~~~~~~~~~~~~~~~~~~~
19
20You can reset your password by clicking on ``Forgot your password?`` link, on the login page. Then, fill the form with your email address