Merge pull request #2016 from wallabag/update-documentation

Update documentation

10 files changed, 144 insertions, 93 deletions

diff --git a/docs/en/developer/api.rst b/docs/en/developer/api.rst
index 3de8ba05..9594f9af 100644
--- a/docs/en/developer/api.rst
+++ b/docs/en/developer/api.rst
@@ -261,6 +261,8 @@ Have a look on the listing here: http://localhost:8000/api/doc to know each meth
 Third resources
 ---------------
 
-Some applications use our API. Here is a non-exhaustive list of them:
+Some applications or libraries use our API. Here is a non-exhaustive list of them:
 
+- `Java wrapper for the wallabag API <https://github.com/Strubbl/wallabag-java>`_ by Strubbl.
+- `.NET library for the wallabag v2 API <https://github.com/jlnostr/wallabag-api>`_ by Julian Oster.
 - `Python API for wallabag <https://github.com/foxmask/wallabag_api>`_ by FoxMaSk, for his project `Trigger Happy <https://blog.trigger-happy.eu/>`_.
diff --git a/docs/en/developer/documentation.rst b/docs/en/developer/documentation.rst
new file mode 100644
index 00000000..ab206479
--- /dev/null
+++ b/docs/en/developer/documentation.rst
@@ -0,0 +1,12 @@
+Contribute to this documentation

+================================

+

+Sources of our documentation are here https://github.com/wallabag/wallabag/tree/master/docs

+

+We use `ReadTheDocs

+<https://readthedocs.org>`__ to generate it.

+

+Pages are written in `Restructured Text

+<https://en.wikipedia.org/wiki/ReStructuredText>`__ format. You can use online tools like http://rst.aaroniles.net/ or http://rst.ninjs.org/ to preview your articles. 

+

+If you create a new page, don't forget to edit the `index.rst <https://raw.githubusercontent.com/wallabag/wallabag/master/docs/en/index.rst>`__ file to add a link in the sidebar.
\ No newline at end of file
diff --git a/docs/en/index.rst b/docs/en/index.rst
index f4b8628a..03025ef9 100644
--- a/docs/en/index.rst
+++ b/docs/en/index.rst
@@ -8,7 +8,7 @@ wallabag documentation
 **wallabag** is a read-it-later application: it saves a web page by
 keeping content only. Elements like navigation or ads are deleted.
 
-.. note::
+.. tip::
 
     This documentation is about wallabag v2. If you want to read documentation for wallabag v1, `please have a look here <https://github.com/wallabag/documentation>`__.
 
@@ -25,15 +25,15 @@ The main documentation for this application is organized into a couple sections:
 
    user/faq
    user/installation
-   user/migration
    user/upgrade
+   user/migration
+   user/import
    user/create_account
    user/login
    user/configuration
    user/first_article
    user/errors_during_fetching
    user/annotations
-   user/import
    user/download_articles
    user/filters
    user/tags
@@ -47,5 +47,6 @@ The main documentation for this application is organized into a couple sections:
 
    developer/api
    developer/docker
+   developer/documentation
    developer/translate
    developer/maintenance
diff --git a/docs/en/user/create_account.rst b/docs/en/user/create_account.rst
index f0110e55..2e883c88 100644
--- a/docs/en/user/create_account.rst
+++ b/docs/en/user/create_account.rst
@@ -23,24 +23,3 @@ Your account is now activated.
 .. image:: ../../img/user/activated_account.png
    :alt: Welcome on board!
    :align: center
-
-Frequently asked questions
---------------------------
-
-I can't valid the registration form
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Make sure that all fields are well filled:
-
-* valid email address
-* same passwords in two fields
-
-I don't receive my activation email
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Are you sure your email address was correct? Did you check your spams folder?
-
-When I click on the activation link, I've got this message: ``The user with confirmation token "DtrOPfbQeVkWf6N" does not exist``.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You already enabled your account or the URL of the activation email is wrong.
diff --git a/docs/en/user/faq.rst b/docs/en/user/faq.rst
index 04fb25e3..1e36dc26 100644
--- a/docs/en/user/faq.rst
+++ b/docs/en/user/faq.rst
@@ -8,3 +8,28 @@ It seems you have a problem with your ``composer`` installation. Try to uninstal
 
 `Read the documentation about composer to know how to install it
 <https://getcomposer.org/doc/00-intro.md>`__.
+
+I can't valid the registration form
+-----------------------------------
+
+Make sure that all fields are well filled:
+
+* valid email address
+* same passwords in two fields
+
+I don't receive my activation email
+-----------------------------------
+
+Are you sure your email address was correct? Did you check your spams folder?
+
+When I click on the activation link, I've got this message: ``The user with confirmation token "DtrOPfbQeVkWf6N" does not exist``.
+----------------------------------------------------------------------------------------------------------------------------------
+
+You already enabled your account or the URL of the activation email is wrong.
+
+I forgot my password
+--------------------
+
+You can reset your password by clicking on ``Forgot your password?`` link,
+on the login page. Then, fill the form with your email address or your username,
+you'll receive an email to reset your password.
diff --git a/docs/en/user/import.rst b/docs/en/user/import.rst
index d6054d39..63210484 100644
--- a/docs/en/user/import.rst
+++ b/docs/en/user/import.rst
@@ -1,42 +1,5 @@
-Migrate to wallabag
-===================
-
-From wallabag
--------------
-
-Export your data from your wallabag 1.x
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-On your config page, click on ``JSON export`` in the ``Export your wallabag data`` section.
-
-.. image:: ../../img/user/export_wllbg_1.png
-   :alt: Export from wallabag 1.x
-   :align: center
-
-You will have a ``wallabag-export-1-1970-01-01.json`` file.
-
-Export your data from your wallabag 2.x
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-On the export sidebar, click on ``JSON``.
-
-.. image:: ../../img/user/export_wllbg_2.png
-   :alt: Export from wallabag 2.x
-   :align: center
-
-You will have a ``Unread articles.json`` file.
-
-Import your data into wallabag 2.x
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Click on  ``Import`` link in the menu, choose the right wallabag version,
-select your export file on your computer and import it.
-
-.. image:: ../../img/user/import_wllbg.png
-   :alt: Import from wallabag 1.x
-   :align: center
-
-All your wallabag articles will be imported.
+Migrate from a third service
+============================
 
 From Pocket
 -----------
@@ -53,7 +16,7 @@ a new application on their developer website to continue.
   and submit your new application
 
 Pocket will give you a **Consumer Key** (for example, `49961-985e4b92fe21fe4c78d682c1`).
-You need to configure the ``pocket_consumer_key`` into the ``app/config/parameters.yml`` file in wallabag.
+You need to configure the ``pocket_consumer_key`` into the ``Import`` section in the ``Internal settings`` menu.
 
 Now, all is fine to migrate from Pocket.
 
diff --git a/docs/en/user/installation.rst b/docs/en/user/installation.rst
index c2174a53..d22f8549 100644
--- a/docs/en/user/installation.rst
+++ b/docs/en/user/installation.rst
@@ -34,6 +34,9 @@ and it's corresponding database server.
 Installation
 ------------
 
+On a dedicated web server (recommended way)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 wallabag uses a big number of libraries in order to function. These libraries must be installed with a tool called Composer. You need to install it if you don't already have.
 
 Install Composer:
@@ -54,7 +57,7 @@ To install wallabag itself, you must run these two commands:
     SYMFONY_ENV=prod composer install --no-dev -o --prefer-dist
     php bin/console wallabag:install --env=prod
 
-To start php's build-in server and test if everything did install correctly, you can do:
+To start PHP's build-in server and test if everything did install correctly, you can do:
 
 ::
 
@@ -62,14 +65,48 @@ To start php's build-in server and test if everything did install correctly, you
 
 And access wallabag at http://yourserverip:8000
 
-.. note::
+.. tip::
 
     To define parameters with environment variables, you have to set these variables with ``SYMFONY__`` prefix. For example, ``SYMFONY__DATABASE_DRIVER``. You can have a look to the `Symfony documentation <http://symfony.com/doc/current/cookbook/configuration/external_parameters.html>`__.
 
-Installing on Apache
---------------------
+On a shared hosting
+~~~~~~~~~~~~~~~~~~~
+
+We provide you a package with all dependancies inside.
+The default configuration uses SQLite for the database. If you want to change these settings, please edit ``app/config/parameters.yml``.
+
+We already created a user: login and password are ``wallabag``.
+
+.. caution:: With this package, wallabag don't check mandatory extensions used in the application (theses checks are made during ``composer install`` when you have a dedicated web server, see above).
+
+Execute this command to download and extract the latest package:
+
+.. code-block:: bash
 
-Assuming you install wallabag in the /var/www/wallabag folder and that you want to use php as an Apache module, here's a vhost for wallabag:
+    wget http://wllbg.org/latest-v2-package && tar xvf latest-v2-package
+
+Now, read the following documentation to create your virtual host, then access to your wallabag.
+If you changed the database configuration to use MySQL or PostgreSQL, you need to create a user via this command ``php bin/console wallabag:install --env=prod``.
+
+Installation with Docker
+------------------------
+
+We provide you a Docker image to install wallabag easily. Have a look to our repository on `Docker Hub <https://hub.docker.com/r/wallabag/wallabag/>`__ to have more information.
+
+Command to launch container
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    docker pull wallabag/wallabag
+
+Virtual hosts
+-------------
+
+Configuration on Apache
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Assuming you install wallabag in the ``/var/www/wallabag`` folder and that you want to use PHP as an Apache module, here's a vhost for wallabag:
 
 ::
 
@@ -111,10 +148,10 @@ Assuming you install wallabag in the /var/www/wallabag folder and that you want
 
 After reloading or restarting Apache, you should now be able to access wallabag at http://domain.tld.
 
-Installing on Nginx
--------------------
+Configuration on Nginx
+~~~~~~~~~~~~~~~~~~~~~~
 
-Assuming you install wallabag in the /var/www/wallabag folder, here's the recipe for wallabag :
+Assuming you install wallabag in the ``/var/www/wallabag`` folder, here's the recipe for wallabag :
 
 ::
 
@@ -151,22 +188,57 @@ Assuming you install wallabag in the /var/www/wallabag folder, here's the recipe
 
 After reloading or restarting nginx, you should now be able to access wallabag at http://domain.tld.
 
-.. note::
+.. tip::
 
     When you want to import large file into wallabag, you need to add this line in your nginx configuration ``client_max_body_size XM; # allows file uploads up to X megabytes``.
 
+Configuration on lighttpd
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Assuming you install wallabag in the /var/www/wallabag folder, here's the recipe for wallabag (edit your ``lighttpd.conf`` file and paste this configuration into it):
+
+::
+
+    server.modules = (
+        "mod_fastcgi",
+        "mod_access",
+        "mod_alias",
+        "mod_compress",
+        "mod_redirect",
+        "mod_rewrite",
+    )
+    server.document-root = "/var/www/wallabag/web"
+    server.upload-dirs = ( "/var/cache/lighttpd/uploads" )
+    server.errorlog = "/var/log/lighttpd/error.log"
+    server.pid-file = "/var/run/lighttpd.pid"
+    server.username = "www-data"
+    server.groupname = "www-data"
+    server.port = 80
+    server.follow-symlink = "enable"
+    index-file.names = ( "index.php", "index.html", "index.lighttpd.html")
+    url.access-deny = ( "~", ".inc" )
+    static-file.exclude-extensions = ( ".php", ".pl", ".fcgi" )
+    compress.cache-dir = "/var/cache/lighttpd/compress/"
+    compress.filetype = ( "application/javascript", "text/css", "text/html", "text/plain" )
+    include_shell "/usr/share/lighttpd/use-ipv6.pl " + server.port
+    include_shell "/usr/share/lighttpd/create-mime.assign.pl"
+    include_shell "/usr/share/lighttpd/include-conf-enabled.pl"
+    dir-listing.activate = "disable"
+
+    url.rewrite-if-not-file = (
+        "^/([^?])(?:\?(.))?" => "/app.php?$1&$2",
+        "^/([^?]*)" => "/app.php?=$1",
+    )
 
 Rights access to the folders of the project
 -------------------------------------------
 
-
-Test Environment
+Test environment
 ~~~~~~~~~~~~~~~~
 
 When we just want to test wallabag, we just run the command ``php bin/console server:run --env=prod`` to start our wallabag instance and everything will go smoothly because the user who started the project can access to the current folder naturally, without any problem.
 
-
-Production Environment
+Production environment
 ~~~~~~~~~~~~~~~~~~~~~~
 
 As soon as we use Apache or Nginx to access to our wallabag instance, and not from the command  ``php bin/console server:run --env=prod`` to start it, we should take care to grant the good rights on the good folders to keep safe all the folders of the project.
@@ -180,4 +252,3 @@ This is due to the fact that we will need to grant the same rights access on the
 .. code-block:: bash
 
    chown -R www-data:www-data /var/www/wallabag/var
-
diff --git a/docs/en/user/login.rst b/docs/en/user/login.rst
index 1813f3d8..e66089bd 100644
--- a/docs/en/user/login.rst
+++ b/docs/en/user/login.rst
@@ -11,13 +11,3 @@ you can check the ``Keep me logged in`` checkbox: wallabag will remember you for
 .. image:: ../../img/user/login_form.png
    :alt: Login form
    :align: center
-
-Frequently asked questions
---------------------------
-
-I forgot my password
-~~~~~~~~~~~~~~~~~~~~
-
-You can reset your password by clicking on ``Forgot your password?`` link,
-on the login page. Then, fill the form with your email address or your username,
-you'll receive an email to reset your password.
diff --git a/docs/en/user/migration.rst b/docs/en/user/migration.rst
index e97c6315..e141ae40 100644
--- a/docs/en/user/migration.rst
+++ b/docs/en/user/migration.rst
@@ -1,5 +1,5 @@
-Migrate wallabag
-================
+Migrate from v1 or v2
+=====================
 
 From wallabag 1.x
 -----------------
diff --git a/docs/en/user/upgrade.rst b/docs/en/user/upgrade.rst
index e4735631..7782dc8a 100644
--- a/docs/en/user/upgrade.rst
+++ b/docs/en/user/upgrade.rst
@@ -5,6 +5,7 @@ Upgrade on a dedicated web server
 ---------------------------------
 
 The last release is published on https://www.wallabag.org/pages/download-wallabag.html. In order to upgrade your wallabag installation and get the last version, run the following commands in you wallabag folder (replace ``2.0.3`` by the last release number):
+
 ::
 
     git fetch origin
@@ -12,12 +13,19 @@ The last release is published on https://www.wallabag.org/pages/download-wallaba
     git checkout 2.0.3
     SYMFONY_ENV=prod composer install --no-dev -o --prefer-dist
     php bin/console cache:clear --env=prod
-    
 
 Upgrade on a shared hosting 
 ---------------------------
 
-Backup your ``app/config/parameters.yml`` file. Extract the archive in your wallabag folder and replace ``app/config/parameters.yml`` with yours.
+Backup your ``app/config/parameters.yml`` file.
+
+Download the last release of wallabag: 
+
+.. code-block:: bash
+
+    wget http://wllbg.org/latest-v2-package && tar xvf latest-v2-package
+
+Extract the archive in your wallabag folder and replace ``app/config/parameters.yml`` with yours.
 
 If you use SQLite, you must also copy your ``data/`` folder inside the new installation.