From 59e91bc8931a386974a3817e9849aad1ca7fc186 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicolas=20L=C5=93uillet?= Date: Wed, 21 Oct 2015 14:14:51 +0200 Subject: add docs --- docs/en/Administrator/hidden_options.rst | 85 +++++++++++ docs/en/Administrator/install.rst | 200 +++++++++++++++++++++++++ docs/en/Administrator/multiusers.rst | 47 ++++++ docs/en/Administrator/sessions.rst | 26 ++++ docs/en/Administrator/update.rst | 30 ++++ docs/en/Developer/create_new_theme.rst | 4 + docs/en/Developer/git_repo.rst | 29 ++++ docs/en/Developer/write_config_files.rst | 52 +++++++ docs/en/User/configure_wallabag.rst | 118 +++++++++++++++ docs/en/User/epub_conversion.rst | 32 ++++ docs/en/User/framabag_account_creation.rst | 49 +++++++ docs/en/User/import_export.rst | 107 ++++++++++++++ docs/en/User/issue_with_article.rst | 36 +++++ docs/en/User/organize_articles.rst | 109 ++++++++++++++ docs/en/User/read_an_article.rst | 63 ++++++++ docs/en/User/rss_feed.rst | 41 ++++++ docs/en/User/save_your_first_article.rst | 226 +++++++++++++++++++++++++++++ docs/en/User/search.rst | 21 +++ docs/en/conf.py | 87 +++++++++++ docs/en/index.rst | 57 ++++++++ docs/en/requirements.txt | 2 + docs/en/user/configuration.rst | 61 ++++++++ docs/en/user/create_account.rst | 43 ++++++ docs/en/user/first_article.rst | 79 ++++++++++ docs/en/user/login.rst | 20 +++ 25 files changed, 1624 insertions(+) create mode 100644 docs/en/Administrator/hidden_options.rst create mode 100644 docs/en/Administrator/install.rst create mode 100644 docs/en/Administrator/multiusers.rst create mode 100644 docs/en/Administrator/sessions.rst create mode 100644 docs/en/Administrator/update.rst create mode 100644 docs/en/Developer/create_new_theme.rst create mode 100644 docs/en/Developer/git_repo.rst create mode 100644 docs/en/Developer/write_config_files.rst create mode 100644 docs/en/User/configure_wallabag.rst create mode 100644 docs/en/User/epub_conversion.rst create mode 100644 docs/en/User/framabag_account_creation.rst create mode 100644 docs/en/User/import_export.rst create mode 100644 docs/en/User/issue_with_article.rst create mode 100644 docs/en/User/organize_articles.rst create mode 100644 docs/en/User/read_an_article.rst create mode 100644 docs/en/User/rss_feed.rst create mode 100644 docs/en/User/save_your_first_article.rst create mode 100644 docs/en/User/search.rst create mode 100644 docs/en/conf.py create mode 100644 docs/en/index.rst create mode 100644 docs/en/requirements.txt create mode 100644 docs/en/user/configuration.rst create mode 100644 docs/en/user/create_account.rst create mode 100644 docs/en/user/first_article.rst create mode 100644 docs/en/user/login.rst (limited to 'docs/en') 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``. 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 @@ +Create new theme +================ + +TODO 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 @@ +Git repository +============== + +If you wish to contribute to the project by suggesting new features or +by fixing some bugs, please follow the recommendations below regarding +the git repository available at https://github.com/wallabag/wallabag. + +Current state +------------- + +To manage the different versions of wallabag, we use Git. + +There are multiple branches for the source code of wallabag web app: + +- ``master`` branch : this is the stable branch, downloaded by those + who wish to install wallabag for their own use. +- ``dev`` branch : before being added on ``master`` branch, all bug + fixes and new features must go on that branch. This branch is not + recommended for production use. +- ``v2`` branch : this is the branch for a revamp of wallabag. + A whole chapter is to be focused on it. + +Workflow +-------- + +All the rules for contributing to the git repository are in the +`CONTRIBUTING.md file of +wallabag `__. +Please 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 @@ +Write config files +================== + +wallabag can use specific site config files to parse website articles. +These files are stored in the +```inc/3rdparty/site_config/standard`` `__ +folder. + +The format used for these files is +`XPath `__. Look at some examples in the +folder. + +Automatic config files generation +--------------------------------- + +Fivefilters has created a `very useful +tool `__ to create config files. You +just type in the adress of the article to work on with, and you select +the area containing the content you want. + +.. figure:: https://lut.im/RNaO7gGe/l9vRnO1b + :alt: siteconfig + + siteconfig +| You should confirm this area by trying with other articles. +| When you got the right area, just click on *Download Full-Text RSS +site config* to download your file. + +Manual config file generation +----------------------------- + +If Fivefilters tool doesn't work correctly, take a look at the source +(Ctrl + U on Firefox and Chromium). Search for your content and get the +``class`` or the ``id`` attribute of the area containing what you want. + +Once you've got the id or class, you can write for example one or +another of these lines: + +:: + + body: //div[@class='myclass'] + body: //div[@id='myid'] + +Then, test you file. If you got the right content but you want to strip +unnecessary parts, do: + +:: + + strip: //div[@class='hidden'] + +You can look at other options for siteconfig files +`here `__. 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 @@ +.. _`Configure wallabag`: + +Configure wallabag +================== + +From the configuration menu, you can change some of wallabag's options. + +Some parts won't be detailed here, as they have a dedicated chapter in +the documentation (:ref:`RSS feeds`, :ref:`Import / Export`, :ref:`ePub conversion` and :ref:`Multi users`). + +Saving articles +--------------- + +You'll find help about the different ways to save articles to your +wallabag here. + +Save article field +~~~~~~~~~~~~~~~~~~ + +Enter a link in the field and click “bag it!” to save. + +Browser extensions +~~~~~~~~~~~~~~~~~~ + +Links to download extensions for your favourite browser, Firefox or +Chrome. + +Mobile apps +~~~~~~~~~~~ + +Links to download mobile apps, Android, iOS or Windows Phone. + +For Android, you have the choice to download either from Google's Play +Store of from the Free and Open Source market +`F-Droid `__ + +Bookmarklet +~~~~~~~~~~~ + +Lastly, you can use the bookmarklet. A bookmarklet is a simple link you +can drag to your browser's bookmarks. Once it's in your bookmarks, +simply clicking on it will save the webpage you're currently viewing to +your wallabag. + +Feeds +----- + +Plese refer to `RSS feeds `__ for more details. + +.. _`Howto change theme`: + +Theme +----- + +As they say, “all tastes and colors are found in nature”. That's why +wallabag allows you to change its appearance through the use of themes, +in order to please everyone. + +Select the theme of your choice from the drop down list and confirm by +clicking on **Update**. + +Language +-------- + +Select the language of your choice in the drop down list and confirm by +clicking on **Update**. + +Import +------ + +Please refer to `Import/Export `__ for more details. + +Export +------ + +Please refer to `Import/Export `__ for more details. + +Clear the cache +--------------- + +The cache allows wallabag perform certain functions faster. + +After updating wallabag, it is advised to clear the cache. + +Click on “delete cache” to do so (no confirmation will be asked). + +Password +-------- + +Fill in your new password in the two dedicated fields and confirm by +clicking on **Update**. + +You will be disconnected and will have to enter your new password to +access your wallabag. + +User +---- + +Add a user here by entering their name, password and (optionnaly) email +in the corresponding fields. + +You may not be able to add a user if don't have the rights to do so. + +Remind newly created users to change their password the first time they +connect to wallabag! + +Delete +------ + +Delete your user account on wallabag here. + +If there is only one account, you won't be able to delete the account. + +Upgrade +------- + +Wallabag will check its curent version and if there is a new version +available 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 @@ +.. _`ePub conversion`: + +ePub conversion +=============== + +To enable you to read your articles on a e-reader, wallabag can convert +them to the ePub format, and hence create an eBook for your long winter +evenings. + +A word of caution +----------------- + +Be careful, the creation of ePub files can be very resource demanding +for the server on which wallabag is installed. It depends on the number +of articles and on their length. Do not create a really big eBook if +this is not necessary. + +Where to convert the articles +----------------------------- + +You can convert your articles at various places in wallabag: + +- on the reading page of an article: the ePub link will convert this + article only +- from the list of articles (unread, favorite or archived articles, + articles with a tag): a link at the bottom of the page allows you to + convert all the article of this category +- from a search: the link is at the bottom of the page +- from the configuration page: you can convert all your articles, + whatever the category to which they belong + +TODO 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 @@ +.. _`Framabag account creation`: + +Framabag account creation +========================= + +If you do not want to install and update wallabag, or if you do not have +the know-how to install it, it is possible to create an account for free +at `Framabag.org `__. + +Account creation +---------------- + +Click on the button **Créez votre compte / Create your account**. + +You have to input some information: your username, your password and +your email address. Your address is used only to validate your account, +except if you check the box to subscribe the newsletter (3 to 4 messages +per year). + +Once this form validated, you will receive an email with the +confirmation link. Click on it to create your account. + +You will receive a last email with the address of your Framabag account, +which will look like ``https://www.framabag.org/u/Your-username``. + +Information storage +------------------- + +Framabag use one database per user. We do not and will not use your +stored data. + +You have forgotten your password +-------------------------------- + +| If you have forgotten your password to get connected to Framabag, a +form is available `on the main page of the +service `__. +| Fill it, and a confirmation will be sent to you and will allow you to +input a new password. + +Account deletion +---------------- + +If you wish to delete your account, contact us by email: +hello@wallabag.org using the address your created your account with, and +state your username. + +We will answer you after your account has been deleted: then, no +information 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 @@ +.. _`Import / Export`: + +Import and export data +====================== + +Import +------ + +To import data in wallabag, go to the page **Configuration**. + +Caution +~~~~~~~ + +Data import can be a **demanding process** for your server. Hence, it is +done in two steps: + +- Insertion of the URL in the wallabag database +- in the second step, the retrieval, for each article, of its full + content. + +These two steps cannot be done concurrently, because it let us the +possibility to import thousands of links, but today, wallabag does not +have sufficient technical capabilities to do this task automatically. + +From Pocket +~~~~~~~~~~~ + +Export your data from Pocket +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +From your Pocket account, go to the options. TODO + +Import your Pocket data +^^^^^^^^^^^^^^^^^^^^^^^ + +From the configuration page of wallabag, section **Import**, select the +file ``ril_export.html`` generated by Pocket, then click on **Import**. +Wallabag only insert these links in the database. Now, you have to get +the content of each article. + +For this, click on ``Click to finish import``: wallabag will fetch the +content of 10 articles at a time. + +TODO + +TODO new ticket: why when a click is done, this does not load in a loop? +I believe this was doing this ping @mariroz + +From Instapaper +~~~~~~~~~~~~~~~ + +Export your data from Instapaper +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +TODO + +Import your Instapaper data +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +TODO + +From Readability +~~~~~~~~~~~~~~~~ + +Export your data from Readability +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +TODO + +Import your Readability data +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +TODO + +From wallabag +~~~~~~~~~~~~~ + +Since you can export your data from wallabag (see below), it is of +course possible to re-import them. + +In the import form, select your wallabag-exported file (format JSON). +Start the import, et voilà. + +Unlike the above imports, this process is shorter because all the data +(title and content of the articles) are already included in the file. +Hence wallabag does not have to access each URL. However, the import +file is necessarily bigger. + +From a HTML or JSON file +~~~~~~~~~~~~~~~~~~~~~~~~ + +TODO + +Export +------ + +It is possible to export your data from the page **Configuration** of +wallabag. Several reasons to do this: + +- re-install of wallabag +- leave the Framabag service to install your own wallabag +- a user with an account on a multi-user wallabag want to have his/her + own wallabag installation +- ... + +This will lead you to download a file `at the JSON +format `__. 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 @@ +.. _`Article is not displayed properly`: + +My article is not displayed properly in wallabag +================================================ + +If you think wallabag do not copy well the content of an article (empty +or incomplete text), here are some suggestions. + +Ask for help +------------ + +Via an email or a ticket, do not forget to give some information that +are important for us to better solve the problem: + +- The URL of the article +- What wallabag displays +- What you were expecting +- The wallabag version of if you use Framabag + +Open a ticket on github +~~~~~~~~~~~~~~~~~~~~~~~ + +To open a new ticket, you should `go to +github `__. An account +is required. Do not forget to send us the information listed above. + +Send us an email +~~~~~~~~~~~~~~~~ + +Send us the link in a email to the address +`hello@wallabag.org `__. Do not forget to send us the information listed above. + +Solve this display problem +-------------------------- + +TODO 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 @@ +.. _`Organize articles`: + +Organize articles +================= + +To be able to find more easily your articles, several methods are +available. + +Tags +---- + +Assign a tag +~~~~~~~~~~~~ + +When saving an article +^^^^^^^^^^^^^^^^^^^^^^ + +To tag an article when saving it, just click on the tag icon next to the +URL field before hitting the Save button. At the moment, it is possible +only to do this from the web interface, but it could come to some apps +or extensions. + +From the article +^^^^^^^^^^^^^^^^ + +To tag an already-saved article, go to the reading page of the article. +There is a part ``tags`` followed with a pencil. Click on the pencil. + +Input in the box the tags you want to assign. Add as many tags as you +want. They need to be separated by commas and not spaces. +Auto-completion is available here: when you type the first letters of an +existing tag, it is not necessary to type the whole word. Select it in +the drop-down list. Once all your tags are inputted, click on the button +**Tag**. + +Then, you can go back to your article and read it. + +From the search +^^^^^^^^^^^^^^^ + +A full chapter on search is available. Here, we will describe only how +to assign a tag from your search. + +When your search displays results, there is a link +``Apply the tag ABCD to this search`` at the bottom of the page. Click +on it: a tad depending on your search (here ``ABCD``) will be assigned +to all the articles found. + +Find all the articles with a given tag +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the wallabag menu, click on **Tags**. Then, all the tags you have +created are displayed, sorted by the number of articles for each tag. +Click on one of these tags to find all the articles with this tag. + +Preferred articles +------------------ + +When you wish to set aside an article, you can mark it as preferred. + +Set an article as favorite +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +From the reading page of an article, or from a list of articles (such as +the list of unread articles), you can set an article as favorite simply +by a click on the star which is displayed. Click again on the star will +remove the **favorite** status of this article. + +Find all the favorite articles +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the wallabag menu, click on **Favorites** to display the list of all +the articles that you have set as favorite. + +Archived articles +----------------- + +When you have read an article, you can archive it: hence it will not be +displayed in your list of unread articles. + +Archiving an article does not remove it from wallabag. + +Archive an article +~~~~~~~~~~~~~~~~~~ + +| From the reading page of an article, or from a list of articles (such +as the list of unread articles), you can archive an article simply by +clicking on the icon ✓. +| Click again on this icon will set back the **unread** status of the +article. + +Find all the archived articles +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the wallabag menu, click on **Archive** to find all the articles that +you have archived. + +Delete an article +----------------- + +Be cautious: the deletion of an article is **definitive**. It is deleted +from the wallabag database. + +To delete an article, a trash icon is displayed on the page of an +article or of a list of articles (unread articles, favorites or +archived, for example). + +We trust you: that is why there is no confirmation message during the +deletion. 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 @@ +Read an article +=============== + +Reading an article is not difficult in wallabag: you only have to click on the title of the article for it to be displayed. + +Back to where you left the article +---------------------------------- + +If you stop reading an article halfway through, the next time wallabag will open it right where you left off. + +This feature only works with web applications and not with smartphone applications. + +Possible actions in an article +------------------------------ + +The 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. + +Here are the actions, in the order of appearance of the icons. + +Read the original article +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Open the article on its original location. + +Mark the article as read +~~~~~~~~~~~~~~~~~~~~~~~~ + +Archive 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. + +Mark the article as favorite +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mark 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. + +Delete the article +~~~~~~~~~~~~~~~~~~ + +Delete the article from wallabag permanently. It cannot be restored. Be careful: no confirmation message is displayed. + +Share through twitter +~~~~~~~~~~~~~~~~~~~~~ + +Share the title and the original link of the article on twitter. + +Share via email +~~~~~~~~~~~~~~~ + +Share the title and the original link of the article via e-mail. + +Print the article +~~~~~~~~~~~~~~~~~ + +Open the print window of the browser. + +Convert into ePub +~~~~~~~~~~~~~~~~~ + +Convert the article into ePub format: see the section on :ref:`ePub conversion`. + +Notify us that the article appears wrong +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Notify 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 @@ +.. _`RSS feeds`: + +RSS feeds +========= + +The RSS feeds allow you to: + +- read your articles from your favorite RSS feed reader. +- to activate the reading features for smartphone softwares + +| First, you must activate the RSS feature by generating a feed token. +| Go to **config** in wallabag and generate a token in the section +**Feeds**. You can generate a new token at any time. + +Read articles +------------- + +Once the token created, you have access to three RSS feeds: + +- the one of the unread articles +- the one of the favorites articles +- the one of the archived articles + +Add the feed you want to your RSS feed reader. Be careful: when you will +be reading an article from your feed reader, this will not set it as +read in wallabag. + +Share your readings +~~~~~~~~~~~~~~~~~~~ + +If you wish to share your readings with somebody, send him for example +the RSS feed of your favorite articles. Hence, as soon as an article +will be set as favorite in wallabag, this person will be able to read it +too. + +Activate the features for smartphones +------------------------------------- + +You ave created an RSS feed token. It will also be useful to you to +configure your smartphone software. For more information about +smartphone 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 @@ +.. _`Save your first article`: + +Save your first article +======================= + +Once connected on wallabag, you have many ways to save an article. + +From the web application +------------------------ + +Let’s see first how to do from the web application. In the menu, you +have a link **save a link**. Clicking on it, a form shows up: you simply +have to type the web adress of the article you want to save. + +Confirm to store the content of the article. + +By default, only the text is saved. If you want to store a copy of the +images on your server, you have to enable the setting +*DOWNLOAD\_PICTURES*. Read the chapter on hidden options for more +information. + +From the bookmarklet +-------------------- + +From `Wikipedia’s definition`_ + + A bookmarklet is a `bookmark`_ stored in a `web browser`_ that + contains `JavaScript`_\ commands to extend the browser’s + functionality. + + Bookmarklets are unobtrusive scripts stored as the URL of a bookmark + in a web browser or as a hyperlink on a web page. + + When clicked, a bookmarklet performs some function, one of a wide + variety such as a search query or data extraction. Bookmarklets are + usually `JavaScript programs`_. + +From the wallabag’s menu, click on **settings**. On the first part of +this page, we have listed all the ways to save an article. You’ll find +the bookmarklet (it’s the ``Bag it!`` link) to drag and drop in the +bookmarks bar of your web browser. From now on, when you want to save +the article you are browsing, you just have to click on this bookmarklet +and the article will be automatically saved. + +From your smartphone +-------------------- + +Above all else +~~~~~~~~~~~~~~ + +To use a smartphone application, you have to enable RSS feeds from the +settings panel of wallabag. Then some information will be displayed, +like your security token. Read the chapter on RSS feeds for more +information. + +Android +~~~~~~~ + +Installation and configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can download the android application from the `Google Play Store`_ +and from `F-droid`_. It’s the exact same application on those two +stores. + +Once installed, start the application, go to the **settings** part et +fill in the **URL (complete address of your wallabag installation or +your Framabag account)** and **User ID (in most cases, you’ll have to +put 1)** fields. If you have created multiple accounts from wallabag, +you will have to to fill the user account you want to connect to your +application and your security **Token** (enter properly all the token’s +letters as seen in the settings part of wallabag). + +Saving of an article +^^^^^^^^^^^^^^^^^^^^ + +Now that everything is correctly set up, as soon as you browse on your +smartphone’s web browser, you can share an article in wallabag at any +time from the **Share** menu: you’ll find a **Bag it!** entry which will +add your article in wallabag. + +Reading +^^^^^^^ + +When you open the application, click on Synchronize: your recently saved +articles will be downloaded on your smartphone. + +You don’t need an internet connection anymore: click on **List +articles** to start your reading. + +At the end of each article, a **Mark as read** button allows you to +archive the article. + +To date, the synchronisation occurs in one direction (from wallabag to +the application), thus preventing mark as read an article on wallabag +from your smartphone. + +iOS +~~~ + +Installation and configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can download the iOS application from the `AppStore`_. + +Once installed, configure the app by filling following fields inside the +settings: the **URL (complete address of your wallabag installation or +your Framabag account)** and **User ID (in most cases, you’ll have to +put 1)** field. If you have created multiple accounts from wallabag, you +will have to to fill the user account you want to connect to your +application and your security **Token** (enter properly all the token’s +letters as seen in the settings part of wallabag). + +Usage +^^^^^ + +If the app is configured correctly, the app will automatically download +the articles from your wallabag (use **pull-to-refresh** to trigger this +update manually). Once an article is downloaded, it’ll be available +offline from your app. + +Unfortunately you can only locally mark an article as read (it will not +synchronise to your online wallabag). + +Saving articles +~~~~~~~~~~~~~~~ + +If you’re browsing a website and want to add the current article to your +wallabag, simply tap the **Share**-button and select **Bag it!** (if you +don’t find the wallabag icon, have a look in the **more**-menu). If +everything is set up correctly, your article will be saved (you may have +to login from time to time). + +Windows Phone +~~~~~~~~~~~~~ + +Installation and configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can download the Windows Phone application from the `Windows Store`_ +or directly from your smartphone’s Store. + +Once installed, the application will show you a notification on the +first launch, asking the configuration of your wallabag server. Go to +the **Settings** part of the application by pressing the three dots menu +at the bottom of the screen, then fill in the **URL (complete address of +your wallabag installation or your Framabag account)** and **User ID (in +most cases, you’ll have to put 1)** fields. + +If you have created multiple accounts from wallabag, you will have to to +fill the user account you want to connect to your application and your +security **Token** (enter properly all the token’s letters as seen in +the setting part of wallabag). + +From your web browser +--------------------- + +Firefox Classic Add-on +~~~~~~~~~~~~~~~~~~~~~~ + +Download the Firefox add-on at `addons.mozilla.org`_ and install it like +any other Firefox add-on. + +In the add-on’s settings, fill the complete URL of your installation of +wallabag or your Framabag account. + +Personalize the Firefox toolbar to add wallabag (**W** icon). When you +find an article you want to save, click on this icon: a new window will +open to add the article and will close itself automatically. + +Firefox Social API Service +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +*Available from wallabag v1.9.1 only* + +You will need an https connection to use this. It’s a Firefox +`requirement`_, sorry. + +With Firefox 29+ versions, your browser comes with an integrated +interface to share things to multiple social services directly from your +browser. In the Firefox interface, it is shown a paper plane-like icon +that you will use to share a page, which means here, save an article. +You can add the service by going into the Config page of wallabag, then +click on Mozilla Services Social API Extension. You must also accept to +use Firefox Services. + +Chrome +~~~~~~ + +Download the Chrome add-on `on the dedicated website`_ and install it +like any other Chrome add-on. + +In the add-on’s settings, fill the complete URL of your installation of +wallabag or your Framabag account. + +During the addon’s installation, a new icon appear in Chrome toolbar (a +**W** icon). When you find an article you want to save, click on this +icon: a popup will appear to confirm that your article has been saved. + +Opera +~~~~~ + +The recent versions of Opera (15+) allow to install add-ons compatible +with Chrome. + +First, install the add-on named `Download Chrome Extensions`_ which will +allow you to install add-ons from the Chrome Web Store. Then, go `to to +Google site`_ and get the Chrome add-on by clicking on *Add to Opera*. A +message will invite you to confirm this action because this add-on is +not coming from a certified source. The behavior will be the same as for +Chrome (see above). + +.. _Wikipedia’s definition: http://fr.wikipedia.org/wiki/Bookmarklet +.. _bookmark: http://en.wikipedia.org/wiki/Internet_bookmark +.. _web browser: http://en.wikipedia.org/wiki/Web_browser +.. _JavaScript: http://en.wikipedia.org/wiki/JavaScript +.. _JavaScript programs: http://en.wikipedia.org/wiki/Computer_program +.. _Google Play Store: https://play.google.com/store/apps/details?id=fr.gaulupeau.apps.InThePoche +.. _F-droid: https://f-droid.org/app/fr.gaulupeau.apps.InThePoche +.. _AppStore: https://itunes.apple.com/app/id828331015 +.. _Windows Store: https://www.microsoft.com/en-us/store/apps/wallabag/9nblggh11646 +.. _addons.mozilla.org: https://addons.mozilla.org/firefox/addon/wallabag/ +.. _requirement: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Social_API/Manifest#Manifest_Contents +.. _on the dedicated website: https://chrome.google.com/webstore/detail/wallabag/bepdcjnnkglfjehplaogpoonpffbdcdj +.. _Download Chrome Extensions: https://addons.opera.com/en/extensions/details/download-chrome-extension-9/ +.. _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 @@ +Search content in wallabag +========================== + +To enable you to find an article quickly, we set up a full search +engine. + +Click on **Search** in the wallabag menu. Then, enter your search terms. + +Wallabag will go through all your articles, and lists the ones +containing the search terms in their title, their content or their URL. + +Convert this search into ePub format +------------------------------------ + +You can convert the listed articles to the ePub format, so that you can +read them in your e-reader, for example. Look at :ref:`ePub conversion` for more about this. + +Assign a tag to your search results +----------------------------------- + +You 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 @@ +# -*- coding: utf-8 -*- +# +# wallabag documentation build configuration file, created by +# sphinx-quickstart on Fri Oct 16 06:47:23 2015. + +import sys +import os + +extensions = [] +templates_path = ['_templates'] +source_suffix = '.rst' +master_doc = 'index' +project = u'wallabag' +copyright = u'2013-2015, Nicolas Lœuillet - MIT Licence' +version = '2.0.0' +release = version +exclude_patterns = ['_build'] +pygments_style = 'sphinx' +html_theme = 'default' +html_static_path = ['_static'] +htmlhelp_basename = 'wallabagdoc' +latex_elements = { + +} + +latex_documents = [ + ('index', 'wallabag.tex', u'wallabag Documentation', + u'Nicolas Lœuillet', 'manual'), +] + +man_pages = [ + ('index', 'wallabag', u'wallabag Documentation', + [u'Nicolas Lœuillet'], 1) +] + +texinfo_documents = [ + ('index', 'wallabag', u'wallabag Documentation', + u'Nicolas Lœuillet', 'wallabag', 'One line description of project.', + 'Miscellaneous'), +] + +##### Guzzle sphinx theme + +import guzzle_sphinx_theme +html_translator_class = 'guzzle_sphinx_theme.HTMLTranslator' +html_theme_path = guzzle_sphinx_theme.html_theme_path() +html_theme = 'guzzle_sphinx_theme' + +# Custom sidebar templates, maps document names to template names. +html_sidebars = { + '**': ['logo-text.html', 'globaltoc.html', 'searchbox.html'] +} + +# Register the theme as an extension to generate a sitemap.xml +extensions.append("guzzle_sphinx_theme") + +# Guzzle theme options (see theme.conf for more information) +html_theme_options = { + + # Set the path to a special layout to include for the homepage + # "index_template": "homepage.html", + + # Allow a separate homepage from the master_doc + # homepage = index + + # Set the name of the project to appear in the nav menu + # "project_nav_name": "Guzzle", + + # Set your Disqus short name to enable comments + # "disqus_comments_shortname": "my_disqus_comments_short_name", + + # Set you GA account ID to enable tracking + # "google_analytics_account": "my_ga_account", + + # Path to a touch icon + # "touch_icon": "", + + # Specify a base_url used to generate sitemap.xml links. If not + # specified, then no sitemap will be built. + #"base_url": "http://guzzlephp.org" + + # Allow the "Table of Contents" page to be defined separately from "master_doc" + # tocpage = Contents + + # Allow the project link to be overriden to a custom URL. + # projectlink = http://myproject.url +} 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 @@ +wallabag documentation +====================== + +.. image:: ../img/wallabag.png + :alt: wallabag logo + :align: center + +**wallabag** is a read-it-later application: it saves a web page by +keeping content only. Elements like navigation or ads are deleted. + +The main documentation for the site is organized into a couple sections: + +* :ref:`user-docs` +* :ref:`admin-docs` +* :ref:`dev-docs` + +.. _user-docs: + +.. toctree:: + :maxdepth: 2 + :caption: User Documentation + + user/create_account + user/login + user/configuration + user/first_article + +user/organize +user/filters +User/read_an_article +User/search +User/epub_conversion +User/issue_with_article +User/rss_feed +User/import_export + +.. _admin-docs: + +.. toctree:: + :maxdepth: 2 + :caption: Admin Documentation + + Administrator/install + Administrator/update + Administrator/hidden_options + Administrator/multiusers + Administrator/sessions + +.. _dev-docs: + +.. toctree:: + :maxdepth: 2 + :caption: Developer Documentation + + Developer/write_config_files + Developer/create_new_theme + 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 @@ +Sphinx>=1.3.0,<1.4.0 +guzzle_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 @@ +Configuration +============= + +Now you're logged in, it's time to configure your account as you want. + +Click on ``Config`` menu. You have four tabs: ``Settings``, ``RSS``, ``User information`` and ``Password``. + +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. + +Items per page +~~~~~~~~~~~~~~ + +You can change the number of articles displayed on each page. + +Language +~~~~~~~~ + +You can change the language of wallabag interface. + +RSS +--- + +wallabag provides RSS feeds for each article status: unread, starred and archive. + +Firstly, you need to create a personal token: click on ``Create your token``. +It's possible to change your token by clicking on ``Reset your token``. + +Now you have three links, one for each status: add them into your favourite RSS reader. + +You can also define how many articles you want in each RSS feed (default value: 50). + +User information +---------------- + +You can change your name, your email address and enable ``Two factor authentication``. + +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. + +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. + +.. image:: ../../img/user/2FA_form.png + :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. + +Password +-------- + +You 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 @@ +Create an account +================= + +On the login page, click on ``Register`` button. + +.. image:: ../../img/user/registration_form.png + :alt: Registration form + :align: center + +You have to fill the form. Please sure to type a valid email address, we'll send you an activation email. + +.. image:: ../../img/user/sent_email.png + :alt: Email was sent to activate account + :align: center + +Check 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. + +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/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 @@ +Save your first article +======================= + +The main purpose of wallabag is to save web articles. You have many ways to do it. + +By using a bookmarklet +---------------------- + +On the ``Howto`` page, you have a ``Bookmarklet`` tab. Drag and drop the ``bag it!`` link to your bookmarks bar of your browser. + +Now, 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. + +By using the classic form +------------------------- + +In the top bar of your screen, you have 3 icons. With the first one, a plus sign, you can easily save a new article. + +.. image:: ../../img/user/topbar.png + :alt: Top bar + :align: center + +Click on it to display a new field, paste the article URL inside and press your ``Return`` key. The article is saved. + +By using a browser add-on +------------------------- + +Firefox +~~~~~~~ + +Firefox Classic Add-on +^^^^^^^^^^^^^^^^^^^^^^ + +Download the Firefox add-on at `addons.mozilla.org`_ and install it like +any other Firefox add-on. + +In the add-on’s settings, fill the complete URL of your installation of +wallabag or your Framabag account. + +Personalize the Firefox toolbar to add wallabag (**W** icon). When you +find an article you want to save, click on this icon: a new window will +open to add the article and will close itself automatically. + +Firefox Social API Service +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available from wallabag v1.9.1 only* + +You will need an https connection to use this. It’s a Firefox +`requirement`_, sorry. + +With Firefox 29+ versions, your browser comes with an integrated +interface to share things to multiple social services directly from your +browser. In the Firefox interface, it is shown a paper plane-like icon +that you will use to share a page, which means here, save an article. +You can add the service by going into the Config page of wallabag, then +click on Mozilla Services Social API Extension. You must also accept to +use Firefox Services. + +Chrome +~~~~~~ + +By using your smarphone application +----------------------------------- + +Android +~~~~~~~ + +Firefox OS +~~~~~~~~~~ + +Windows Phone +~~~~~~~~~~~~~ + +iOS +~~~ + + +.. _addons.mozilla.org: https://addons.mozilla.org/firefox/addon/wallabag/ +.. _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 @@ +Login +===== + +Your account is now enabled, congratulations! + +To login to wallabag, fill the form on login page. + +If 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. + +.. 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 -- cgit v1.2.3