Merge pull request #1495 from wallabag/v2-docs

add docs

5 files changed, 388 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 @@
+Hidden options
+==============
+
+Caution
+-------
+
+**Be careful**, this section is destined to advanced users. We are going
+to modify an important wallabag configuration file,
+``inc/poche/config.inc.php``. It is therefore advised to do a backup of
+this file before you proceed. **Any error occuring during the
+modification of a wallabag file could lead to malfunctions**.
+
+This file is created when you install wallabag. Install wallabag, do a
+backup copy of the file, then open it in your favorite text editor.
+
+In this file, there are some options that are not, as of now, available
+in the **config** page of wallabag.
+
+Modification of advanced options
+--------------------------------
+
+Each option is defined this way:
+
+::
+
+    @define ('OPTION_NAME', 'Value');
+
+For each line, you can only modify the ``Value`` field.
+
+Here is the list of each option you can change:
+
+-  ``HTTP_PORT`` (default: ``80``) : the HTTP port of your web server.
+   You may need to change it if your server is behind a proxy. Accepted
+   values: number
+-  ``SSL_PORT`` (default: ``443``) : the HTTP port of your web server.
+   You may need to change it if your server use SSLH. Accepted values:
+   number
+-  ``MODE_DEMO`` (default : ``FALSE)``: If you ever wanted to set up a
+   demonstration server… Accepted values: ``TRUE`` or ``FALSE``.
+-  ``DEBUG_POCHE`` (default: ``FALSE``) : if you encounter some problems
+   with wallabag, we may ask you to active Debug mode. Accepted values:
+   ``TRUE`` or ``FALSE``. Check the logs in cache/log.txt after
+   activating that.
+-  ``ERROR_REPORTING`` (default : ``E_ALL & ~E_NOTICE``) : Set to
+   ``E_ALL`` if needed to look for eventual PHP errors.
+-  ``DOWNLOAD_PICTURES`` (default: ``FALSE``) : Allows wallabag to fetch
+   images from the articles you save on your server, instead of fetching
+   only the text. We prefer to let you activate this option yourself.
+   Accepted values: ``TRUE`` or ``FALSE``.
+-  ``REGENERATE_PICTURES_QUALITY`` (default : ``75``) : In order to
+   avoid security problems, pictures are regenerated if you activate the
+   download of pictures. This is the percentage of quality at which they
+   are saved. Increase that numbler if you want better quality, lower if
+   you need better performances.
+-  ``SHARE_TWITTER`` (default: ``TRUE``) : enables Twitter sharing.
+   Accepted values: ``TRUE`` or ``FALSE``.
+-  ``SHARE_MAIL`` (default: ``TRUE``) : enables mail sharing. Accepted
+   values: ``TRUE`` or ``FALSE``.
+-  ``SHARE_EVERNOTE``\ (default : ``FALSE``) : enables sharing with your
+   Evernote account. Accepted values: ``TRUE`` or ``FALSE``.
+-  ``SHARE_DIASPORA`` (default : ``FALSE``) : enables to share an
+   article on your Diaspora account.
+-  ``DIASPORA_URL`` (default : ``http://diasporapod.com``) : The URL of
+   your Diaspora\* pod
+-  ``CARROT`` (default : ``FALSE``) : Like Flattr, it’s a service to
+   give small amounts of money to a web page. See http://carrot.org/
+-  ``SHARE_SHAARLI`` (default: ``FALSE``) : enables sharing via your
+   Shaarli installation (Shaarli is an open-source bookmark manager).
+   Accepted values: ``TRUE`` or ``FALSE``.
+-  ``SHAARLI_URL`` (default: ``'http://myshaarliurl.com'``) : defines
+   your Shaarli installation URL. Accepted values: an URL.
+-  ``FLATTR`` (default: ``TRUE``) : enables the possibility to Flattr an
+   article (`Flattr is a microdonation platform`_). If an article is
+   Flattr-able, an icon will be displayed, allowing you to send a
+   microdonation to the author. Accepted values: ``TRUE`` or ``FALSE``.
+-  ``SHOW_PRINTLINK`` (default: ``'1'``) : enables the Print button for
+   articles. Accepted values: ``'1'`` to enable or ``'0'`` to disable.
+-  ``SHOW_READPERCENT`` (default: ``'1'``) : enables the reading
+   progress on articles (working on the ``default``, ``dark``,
+   ``dmagenta``, ``solarized``, ``solarized-dark`` themes). Accepted
+   values: ``'1'`` to enable or ``'0'`` to disable.
+-  ``PAGINATION`` (default: ``'12'``) : defines the number of articles
+   that are displayed on a list. Accepted values: number.
+
+.. _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 @@
+Download and install wallabag
+=============================
+
+I don’t want to install wallabag
+--------------------------------
+
+If you can’t or don’t want to install Wallabag on your server, we
+suggest you create a free account on `Framabag`_ which uses our
+software (see :ref:`Framabag account creation`).
+
+I want to install wallabag
+--------------------------
+
+I want to download wallabag manually
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`Download the latest wallabag version`_ and unpack it:
+
+::
+
+    wget http://wllbg.org/latest
+    unzip latest
+    mv wallabag-version-number wallabag
+
+Copy the files on your web server. For Ubuntu/Debian, it is the
+directory /var/www/html/ :
+
+::
+
+    sudo mv wallabag /var/www/html/
+
+Then, jump off to next section.
+
+I want to download wallabag via composer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You need to install composer:
+
+::
+
+    curl -s http://getcomposer.org/installer | php
+
+Next, on your web server, run this command:
+
+::
+
+    composer create-project wallabag/wallabag . dev-master
+
+All is downloaded into the current folder.
+
+Prerequisites for your web server
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Wallabag requires that several components to be installed on your web
+server. To make sure your server has all the prerequisites, open in your
+browser the page ``http://monserveur.com/wallabag/install/index.php``.
+
+The components are:
+
+-  `PHP 5.3.3 or above`_ **with `PDO`_ support**
+-  `XML for PHP`_
+-  `PCRE`_
+-  `ZLib`_ (otherwise, the processing of compressed pages will be
+   affected)
+-  `mbstring`_ anb/or `iconv`_ (otherwise some pages will not be read -
+   even in English)
+-  The `DOM/XML`_ extension
+-  `Data filtering`_
+-  `GD`_ (otherwise, pictures will not be saved)
+-  `Tidy for PHP`_ (otherwise, you may encounter problems with some
+   pages)
+-  `cURL`_ with ``Parallel URL fetching`` (optionnal)
+-  `Parse ini file`_
+-  `allow\_url\_fopen`_ (optionnal if cURL is installed)
+-  `gettext`_ (required for multi-language support)
+
+Install the missing components before to proceed. For example, to
+install Tidy on Ubuntu/Debian:
+
+::
+
+    sudo apt-get install php5-tidy
+    sudo service apache2 reload
+
+Note : if you’re using IIS as a webserver, you have to disable
+*Anonymous Authentication* and `enable *Basic Authentication*`_ in order
+to be able to login.
+
+Twig installation
+^^^^^^^^^^^^^^^^^
+
+wallabag is build with Twig, a template library. You have to download it
+for wallabag to work. If you cannot install ``composer`` (for example in
+the case of shared hosting), we offer you to download a file which
+includes ``Twig``. This file can be downloaed from the page
+``http://myservur.com/wallabag/install/index.php`` (section TWIG
+INSTALLATION) or directly at http://wllbg.org/vendor. Uncompress it in
+your wallabag directory.
+
+Otherwise, you can use Composer to install ``Twig`` by launching
+``composer`` from your wallabag directory (in the case of Ubuntu/Debian
+too: /var/www/html/wallabag/) by following the commands written on
+screen:
+
+::
+
+    curl -s http://getcomposer.org/installer | php
+    php composer.phar install
+
+Creation of the database.
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Wallabag can be installed on different types of databases:
+
+-  `SQLite`_. The easiest system of all. No extra configuration needed.
+-  `MySQL`_. A well known database system, which is in most cases more
+   efficient than SQLite.
+-  `PostgreSQL`_. Some people found it better than MySQL.
+
+We advice you to use MySQL because it is more efficient. In this case,
+you should create a new database (for example ``wallabag``), a new user
+(for example ``wallabag``) and a password (here ``YourPassWord``). To do
+this, you can use ``phpMyAdmin``, or launch the following commands:
+
+::
+
+    mysql -p -u root
+    mysql> CREATE DATABASE wallabag;
+    mysql> GRANT ALL PRIVILEGES ON `wallabag`.* TO 'wallabag'@'localhost' IDENTIFIED BY 'VotreMotdePasse';
+    mysql> exit
+
+*Note:* If you’re using MySQL or Postgresql, you have to **fill all the
+fields**, otherwise the installation will not work and an error message
+will tell you what’s wrong. You must create the database that you will
+use for wallabag manually with a tool like PHPMyAdmin or the console.
+
+Permissions
+~~~~~~~~~~~
+
+Your web server needs a writing access to the ``assets``, ``cache`` and
+``db`` directories. Otherwise, a message will report that the
+installation is impossible:
+
+::
+
+    sudo chown -R www-data:www-data /var/www/html/wallabag
+
+Installation of wallabag. At last.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Access to wallabag from your web browser:
+``http://votreserveur.com/wallabag``. If your server is correctly
+configured, you directly reach the setup screen.
+
+Select the type of database (``sqlite``, ``mysql`` or ``postgresql``)
+and fill the information about your database. In the case of the databse
+MySQL created before, the standard configuration will be:
+
+::
+
+    Database engine:    MySQL
+    Server:             localhost
+    Database:           wallabag
+    Username:           wallabag
+    Password:           YourPassWord
+
+Finally, Create your first user and his/her password (different from the
+database user).
+
+Wallabag is now installed.
+
+Login
+-----
+
+From your web browser, you reach the login screen: fill your username
+and your password to connect to your account.
+
+Enjoy!
+
+.. _SQLite: http://php.net/manual/fr/book.sqlite.php
+.. _MySQL: http://php.net/manual/fr/book.mysql.php
+.. _PostgreSQL: http://php.net/manual/fr/book.pgsql.php
+.. _Framabag: https://framabag.org/
+.. _Download the latest wallabag version: http://wllbg.org/latest
+.. _PHP 5.3.3 or above: http://php.net/manual/fr/install.php
+.. _PDO: http://php.net/manual/en/book.pdo.php
+.. _XML for PHP: http://php.net/fr/xml
+.. _PCRE: http://php.net/fr/pcre
+.. _ZLib: http://php.net/en/zlib
+.. _mbstring: http://php.net/en/mbstring
+.. _iconv: http://php.net/en/iconv
+.. _DOM/XML: http://php.net/manual/en/book.dom.php
+.. _Data filtering: http://php.net/manual/fr/book.filter.php
+.. _GD: http://php.net/manual/en/book.image.php
+.. _Tidy for PHP: http://php.net/fr/tidy
+.. _cURL: http://php.net/fr/curl
+.. _Parse ini file: http://uk.php.net/manual/en/function.parse-ini-file.php
+.. _allow\_url\_fopen: http://www.php.net/manual/fr/filesystem.configuration.php#ini.allow-url-fopen
+.. _gettext: http://php.net/manual/fr/book.gettext.php
+.. _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 @@
+.. _`Multi users`:
+
+Multi users
+===========
+
+Create a new account
+--------------------
+
+Administrator mode
+------------------
+
+If you want to use wallabag with several persons, you can create new
+accounts from the configuration page.
+
+At the bottom of this page there is a form where you should input a user
+name and a password.
+
+It is now possible to login to this account from the login page of
+wallabag.
+
+No information are shared among the accounts.
+
+Open registration mode
+----------------------
+
+Starting from version 1.9, the administrator can let users register by
+themselves. This is done by changing the following lines in the
+configuration file:
+
+::
+
+    // registration
+    @define ('ALLOW_REGISTER', FALSE);
+    @define ('SEND_CONFIRMATION_EMAIL', FALSE);
+
+Then, a user will be able to enter his/her user name and password to
+create his/her own account. Depending on the configuration, a
+confimation email can be sent to users who gave an email address.
+
+Remove an account
+-----------------
+
+It is possible to remove your own account from the configuration page.
+You simply have to enter your password and to ask for the removal.
+
+Of course, when there is only one account, it is impossible to remove
+it.
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 @@
+Session issues
+==============
+
+If you end up disconnected even while checking the *Stay signed in
+checkbox*, please run the following commands as root (or with sudo) :
+
+::
+
+    mkdir /var/lib/wallabag-sessions
+    chown www-data:www-data /var/lib/wallabag-sessions
+
+*NOTE : The www-data user and group may not exist, you may use
+``chown http:http /var/lib/wallabag-sessions`` instead*
+
+Then, using apache add:
+``php_admin_value session.save_path /var/lib/wallabag-sessions`` to your
+apache vhost, for instance ``wallabag-apache.conf`` Finally, restart
+apache, for instance like this : ``/etc/init.d/apache2 restart``
+
+If you’re using nginx, add
+``php_admin_value[session.save_path] = /var/lib/wallabag-sessions`` in
+your nginx configuration file. Then, restart nginx :
+``/etc/init.d/nginx restart``
+
+*NOTE : If you’re using systemd, you should do
+``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 @@
+Update wallabag
+===============
+
+Update an existing wallabag installation
+----------------------------------------
+
+In order to update your installation, download and unzip the archive
+into your installation folder. For example on Ubuntu/Debian:
+
+::
+
+    wget http://wllbg.org/latest
+    unzip latest
+    rsync -ur wallabag-version-number/* /var/www/html/wallabag/ # could be another location such as /srv/html, /usr/share/nginx/html
+
+After that, just access wallabag in your browser and follow the
+instructions to finish the update.
+
+You can verify at the bottom of the configuration page that you’re
+running the last version.
+
+**If it fails**, just delete the ``install`` folder and clear the cache:
+
+::
+
+    cd /var/www/html/wallabag/
+    rm -r cache/* install/
+
+Clearing the cache is also possible in the configuration page, clicking
+on the link ``Delete Cache``.