Switch DBMS
-----------
-By default, wallabag will start with a sqlite database.
+By default, wallabag will start with a SQLite database.
Since wallabag provides support for Postgresql and MySQL, docker
containers are also available for these ones.
-In ``docker-compose.yml``, for the chosen DBMS uncomment :
+In ``docker-compose.yml``, for the chosen DBMS uncomment:
- the container definition (``postgres`` or ``mariadb`` root level
block)
- the container env file in the ``php`` container
In order to keep running Symfony commands on your host (such as
-``wallabag:install``), you also should :
+``wallabag:install``), you also should:
- source the proper env files on your command line, so variables
like ``SYMFONY__ENV__DATABASE_HOST`` will exist.
Translate wallabag
==================
+wallabag web application
+------------------------
+
Translation files
------------------
+~~~~~~~~~~~~~~~~~
.. note::
- As wallabag is mainly developed by a French team, please consider that french translation is the most updated one and please copy it to create your own translation.
+ As wallabag is mainly developed by a French team, please consider that french
+ translation is the most updated one and please copy it to create your own translation.
You can find translation files here: https://github.com/wallabag/wallabag/tree/v2/src/Wallabag/CoreBundle/Resources/translations.
-You have to create ``messages.CODE.yml`` and ``validators.CODE.yml``, where CODE is the the ISO 639-1 code of your language (`see wikipedia <https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes>`__).
+You have to create ``messages.CODE.yml`` and ``validators.CODE.yml``, where CODE
+is the ISO 639-1 code of your language (`see wikipedia <https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes>`__).
Other files to translate:
- https://github.com/wallabag/wallabag/tree/v2/app/Resources/CraueConfigBundle/translations.
- https://github.com/wallabag/wallabag/tree/v2/app/Resources/FOSUserBundle/translations.
-You have to create ``CraueConfigBundle.CODE.yml``.
+You have to create ``THE_TRANSLATION_FILE.CODE.yml`` files.
Configuration file
-------------------
+~~~~~~~~~~~~~~~~~~
You have to edit `app/config/config.yml
-<https://github.com/wallabag/wallabag/blob/v2/app/config/config.yml>`__ to display your language on Configuration page of wallabag (to allow users to switch to this new translation).
+<https://github.com/wallabag/wallabag/blob/v2/app/config/config.yml>`__ to display
+your language on Configuration page of wallabag (to allow users to switch to this new translation).
-Under the ``wallabag_core.languages`` section, you have to add a new line for with your translation. For example
+Under the ``wallabag_core.languages`` section, you have to add a new line with
+your translation. For example:
::
fr: 'Français'
-For the first column (``en``, ``fr``, etc.), you have to add the ISO 639-1 code of your language (see above).
+For the first column (``en``, ``fr``, etc.), you have to add the ISO 639-1 code
+of your language (see above).
For the second column, it's the name of your language. Just that.
+
+wallabag documentation
+----------------------
+
+.. note::
+
+ Contrary to the web application, the main language for documentation is english.
+
+Documentation files are stored here: https://github.com/wallabag/wallabag/tree/v2/docs
+
+You need to respect the ``en`` folder structure when you create your own translation.
**wallabag** is a read-it-later application: it saves a web page by
keeping content only. Elements like navigation or ads are deleted.
+.. note::
+
+ 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>`__.
+
The main documentation for this application is organized into a couple sections:
* :ref:`user-docs`
Now you're logged in, it's time to configure your account as you want.
-Click on ``Config`` menu. You have five tabs: ``Settings``, ``RSS``, ``User information``, ``Password`` and ``Tagging rules``.
+Click on ``Config`` menu. You have five tabs: ``Settings``, ``RSS``,
+``User information``, ``Password`` and ``Tagging rules``.
Settings
--------
Theme
~~~~~
-wallabag 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.
+wallabag is customizable. You can choose your prefered theme here. You can also
+create a new one, a chapter will be dedicated for this. The default theme is
+``Material``, it's the theme used in the documentation screenshots.
Items per page
~~~~~~~~~~~~~~
Language
~~~~~~~~
-You can change the language of wallabag interface.
+You can change the language of wallabag interface. You need to logout for this change
+to take effect.
RSS
---
Two factor authentication
~~~~~~~~~~~~~~~~~~~~~~~~~
- 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.
+ 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.
https://en.wikipedia.org/wiki/Two-factor_authentication
-If 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.
+If 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.
.. image:: ../../img/user/2FA_form.png
- :alt: Two factor authentication
- :align: center
+ :alt: Two factor authentication
+ :align: center
-If 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.
+If 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.
Password
--------
-You can change your password here.
+You can change your password here (8 characters minimum).
Tagging rules
-------------
-If you want to automatically assign a tag to new articles, this part of the configuration is for you.
+If you want to automatically assign a tag to new articles, this part
+of the configuration is for you.
What does « tagging rules » mean?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
They are rules used by wallabag to automatically tag new entries.
-Each time a new entry is added, all the tagging rules will be used to add the tags you configured, thus saving you the trouble to manually classify your entries.
+Each time a new entry is added, all the tagging rules will be used to add
+the tags you configured, thus saving you the trouble to manually classify your entries.
How do I use them?
~~~~~~~~~~~~~~~~~~
-Let assume you want to tag new entries as *« short reading »* when the reading time is inferior to 3 minutes.
-In that case, you should put « readingTime <= 3 » in the **Rule** field and *« short reading »* in the **Tags** field.
+Let assume you want to tag new entries as *« short reading »* when
+the reading time is inferior to 3 minutes.
+In that case, you should put « readingTime <= 3 » in the **Rule** field
+and *« short reading »* in the **Tags** field.
Several tags can added simultaneously by separating them by a comma: *« short reading, must read »*.
-Complex rules can be written by using predefined operators: if *« readingTime >= 5 AND domainName = "github.com" »* then tag as *« long reading, github »*.
+Complex rules can be written by using predefined operators:
+if *« readingTime >= 5 AND domainName = "github.com" »* then tag as *« long reading, github »*.
Which variables and operators can I use to write rules?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
mimetype The entry's mime-type OR One rule or another
readingTime The estimated entry's reading time, in minutes AND One rule and another
domainName The domain name of the entry matches Tests that a subject is matches a search (case-insensitive). Example: title matches "football"
-=========== ============================================== ======== ==========
\ No newline at end of file
+=========== ============================================== ======== ==========
--- /dev/null
+Exécuter wallabag avec docker-compose
+=====================================
+
+Pour faire tourner votre propre instance de développement de wallabag, vous pouvez
+utiliser les fichiers docker pré-configurés.
+
+Pré-requis
+----------
+
+Soyez sur d'avoir `Docker
+<https://docs.docker.com/installation/ubuntulinux/>`__ et `Docker
+Compose <https://docs.docker.com/compose/install/>`__ installés et à jour sur votre
+système.
+
+Changer de SGBD
+---------------
+
+Par défaut, wallabag fonctionne avec une base de données SQLite.
+Depuis que wallabag supporte Postgresql et MySQL, les conteneurs Docker sont
+aussi disponibles pour ces SGBD.
+
+Dans ``docker-compose.yml``, en fonction de votre SGBD, décommentez :
+
+- la définition du conteneur (le block racine ``postgres`` ou ``mariadb``)
+- le conteneur ``links`` dans le conteneur ``php``
+- le conteneur ``env_file`` dans le conteneur ``php``
+
+Pour que les commandes Symfony (par exemple ``wallabag:install``) continuent de
+fonctionner sur votre système, vous devez aussi :
+
+- charger le bon fichier d'environnement dans votre ligne de commandes (``source``),
+pour que les variables comme ``SYMFONY__ENV__DATABASE_HOST`` existent.
+- ajouter une ligne ``127.0.0.1 rdbms`` dans votre fichier ``hosts``
+
+Exécuter wallabag
+-----------------
+
+#. Forker et cloner le projet
+#. Editer ``app/config/parameters.yml`` pour remplacer les propriétés ``database_*``
+ par les lignes commentées (celles avec des valeurs préfixées par ``env.``)
+#. ``composer install`` pour installer les dépendances
+#. ``php app/console wallabag:install`` pour créer le schéma de la BDD
+#. ``docker-compose up`` pour démarrer les conteneurs
+#. Enfin, se rendre sur http://localhost:8080/ pour accéder à une installation
+ tout propre de wallabag.
+
+Il est possible de rencontrer des problèmes de droits UNIX, de mauvais chemins
+dans les fichiers de cache, etc…
+Les opérations comme vider le cache ou restaurer les permissions des fichiers
+peuvent être fréquemment nécessaires, n'ayez crainte !
--- /dev/null
+Traduire wallabag
+=================
+
+L'application web
+-----------------
+
+Fichiers de traductions
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+ Comme wallabag est principalement dévelopée par une équipe française, c'est
+ cette traduction qui est considérée comme la plus récente. Merci de vous baser
+ sur celle-ci pour créer votre traduction.
+
+Les principaux fichiers de traduction se trouvent ici : https://github.com/wallabag/wallabag/tree/v2/src/Wallabag/CoreBundle/Resources/translations.
+
+Vous devez créer les fichiers ``messages.CODE.yml`` et ``validators.CODE.yml``,
+où CODE est le code ISO 639-1 de votre langue (`cf wikipedia <https://fr.wikipedia.org/wiki/Liste_des_codes_ISO_639-1>`__).
+
+Autres fichiers à traduire :
+
+- https://github.com/wallabag/wallabag/tree/v2/app/Resources/CraueConfigBundle/translations.
+- https://github.com/wallabag/wallabag/tree/v2/app/Resources/FOSUserBundle/translations.
+
+Vous devez créer les fichiers ``LE_FICHIER_DE_TRADUCTION.CODE.yml``.
+
+Fichier de configuration
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Vous devez éditer `app/config/config.yml
+<https://github.com/wallabag/wallabag/blob/v2/app/config/config.yml>`__ pour
+afficher votre langue dans la page Configuration de wallabag (pour permettre aux
+utilisateurs de choisir cette nouvelle traduction).
+
+Dans la section ``wallabag_core.languages``, vous devez ajouter une nouvelle ligne
+avec votre traduction. Par exemple :
+
+::
+
+ wallabag_core:
+ ...
+ languages:
+ en: 'English'
+ fr: 'Français'
+
+
+Pour la première colonne (``en``, ``fr``, etc.), vous devez ajouter le code ISO 639-1
+de votre langue (voir ci-dessus).
+
+Pour la seconde colonne, c'est juste le nom de votre langue.
+
+Documentation de wallabag
+-------------------------
+
+.. note::
+
+ Contrairement à l'application, la langue principale de la documentation est l'anglais
+
+Les fichiers de documentation se trouvent ici : https://github.com/wallabag/wallabag/tree/v2/docs
+
+Vous devez respecter la structure du dossier ``en`` quand vous crééz votre traduction.
simplement d’archiver une page web en ne conservant que le contenu. Les
éléments superflus (menu, publicité, etc.) sont supprimés.
+.. note::
+
+ Vous vous trouvez sur la documentation de wallabag v2. Si vous voulez lire la documentation de wallabag v1, `vous pouvez jeter un œil ici <https://github.com/wallabag/documentation>`__.
+
La documentation principale de cette application est découpée en plusieurs sections :
+* :ref:`user-docs`
+* :ref:`dev-docs`
+
+.. _user-docs:
+
+.. toctree::
+:maxdepth: 2
+ :caption: Documentation utilisateur
+
+ user/create_account
+ user/login
+ user/configuration
+ user/first_article
+ user/import
+ user/download_articles
+ user/filters
+ user/tags
+
+.. _dev-docs:
+
.. toctree::
- :maxdepth: 2
+:maxdepth: 2
+ :caption: Documentation développeur
- index
+ developer/docker
+ developer/translate
--- /dev/null
+Configuration
+=============
+
+Maintenant que vous êtes connecté, il est temps de confirurer votre compte.
+
+Cliquez sur le menu ``Configuration``. Vous avez accès à 5 onglets:
+``Paramètres``, ``RSS``, ``Mon compte``, ``Mot de passe`` and ``Règles de tag automatiques``.
+
+Paramètres
+----------
+
+Thème
+~~~~~
+
+L'affichage de wallabag est personnalisable. C'est ici que vous choisissez le thème
+que vous préférez. Vous pouvez aussi en créer un nouveau, une documentation sera
+disponible pour apprendre comment. Le thème par défaut ``Material``, c'est ce thème
+qui est utilisé dans les captures d'écran de la documentation.
+
+Nombre d'articles par page
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Vous pouvez définir le nombre d'articles affichés sur chaque page.
+
+Langue
+~~~~~~
+
+Vous pouvez définir la langue de l'interface de wallabag. Vous devrez vous déconnecter
+pour que la nouvelle langue soit prise en compte.
+
+RSS
+---
+
+wallabag propose un flux RSS for chaque statut d'article : non lus, favoris and lus.
+
+Tout d'abord, vous devez vous créer un jeton personnel : cliquez sur ``Créez votre jeton``.
+C'est possible de regénérer votre jeton en cliquant sur ``Réinitialisez votre jeton``.
+
+Vous avez maintenant trois liens, un par statut : ajoutez les dans votre agrégateur de flux RSS préféré.
+
+Vous pouvez aussi définir combien d'articles vous souhaitez dans vos flux RSS
+(50 est la valeur par défaut).
+
+Mon compte
+----------
+
+Vous pouvez ici modifier votre nom, votre adresse email et activer la ``Double authentification``.
+
+Double authentification (2FA)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ 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.
+
+https://en.wikipedia.org/wiki/Two-factor_authentication
+
+Si vous activer 2FA, à chaque tentative de connexion à wallabag, vous recevrez
+un code par email. Vous devez renseigner ce code dans le formulaire suivant :
+
+.. image:: ../../img/user/2FA_form.png
+ :alt: Two factor authentication
+ :align: center
+
+Si vous ne souhaitez pas recevoir un code à chaque fois que vous vous connectez,
+vous pouvez cocher la case ``Je suis sur un ordinateur de confiance`` : wallabag
+se souviendra de vous pour 15 jours.
+
+Mot de passe
+------------
+
+Vous pouvez changer de mot de passe ici (8 caractères minimum).
+
+Règles de tag automatiques
+--------------------------
+
+Si vous voulez automatiquement assigner un tag à de nouveaux articles en fonction de
+certains critères, cette partie de la configuration est pour vous.
+
+Que veut dire « règles de tag automatiques » ?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Ce sont des règles utilisées par wallabag pour automatiquement assigner un tag
+à un nouvel article.
+À chaque fois que vous ajoutez un nouvel article, toutes les règles sont utilisées pour ajouter
+les tags que vous avez configurés, vous épargnant ainsi la peine de classer manuellement vos articles.
+
+Comment les utiliser ?
+~~~~~~~~~~~~~~~~~~~~~~
+
+Admettons que vous voulez ajouter comme tag *« lecture rapide »* quand le temps de lecture
+d'un article est inférieur à 3 minutes.
+Dans ce cas, vous devez ajouter « readingTime <= 3 » dans le champ **Règle** et *« lecture rapide »* dans le champ **Tags**.
+Plusieurs tags peuvent être ajoutés en même temps en les séparant par une virgule : *« lecture rapide, à lire »*.
+Des règles complexes peuvent être écrites en utilisant les opérateurs pré-définis :
+if *« readingTime >= 5 AND domainName = "github.com" »* then tag as *« long reading, github »*.
+
+Quels variables et opérateurs puis-je utiliser pour écrire mes règles ?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Les variables et opérateurs suivants peuvent être utilisés lors de la création de vos règles :
+
+=========== ============================================== ========== ==========
+Variable Sens Opérateur Sens
+----------- ---------------------------------------------- ---------- ----------
+title Titre de l'article <= Inférieur ou égal à …
+url URL de l'article < Strictement inférieur à …
+isArchived Si l'article est archivé ou non => Supérieur ou égal à …
+isStared Si l'article est en favori ou non > Strictement supérieur à …
+content Le contenu de l'article = Égal à …
+language La langue de l'article != Différent de …
+mimetype The type MIME de l'article OR Telle règle ou telle autre règle
+readingTime Le temps de lecture de l'article, en minutes AND Telle règle et telle règle
+domainName Le nom de domaine de l'article matches Contient telle chaine de caractère (insensible à la casse). Exemple : title matches "football"
+=========== ============================================== ========== ==========
projects / github / wallabag / wallabag.git / commitdiff
