diff --git a/doc/md/Continuous-integration-tools.md b/doc/md/Continuous-integration-tools.md index 4bd7a0b..4ca6bdc 100644 --- a/doc/md/Continuous-integration-tools.md +++ b/doc/md/Continuous-integration-tools.md @@ -2,8 +2,8 @@ A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations: - Documentation - generate a local HTML copy of the GitHub wiki -- [Static analysis](Static analysis) - check that the code is compliant to PHP conventions -- [Unit tests](Unit tests) - ensure there are no regressions introduced by new commits +- [Static analysis](Static-analysis) - check that the code is compliant to PHP conventions +- [Unit tests](Unit-tests) - ensure there are no regressions introduced by new commits ## Automatic builds [Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build: @@ -17,7 +17,8 @@ Each build job: - updates Composer - installs 3rd-party test dependencies with Composer -- runs [Unit tests](Unit tests) +- runs [Unit tests](Unit-tests) +- runs ESLint check After all jobs have finished, Travis returns the results to GitHub: diff --git a/doc/md/Development-guidelines.md b/doc/md/Development-guidelines.md index 532ec2e..46b7c6f 100644 --- a/doc/md/Development-guidelines.md +++ b/doc/md/Development-guidelines.md @@ -3,8 +3,11 @@ Please have a look at the following pages: - [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md) -- [Static analysis](Static analysis) - patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially: +- [Static analysis](Static-analysis) - patches should try to stick to the +[PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially: - [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard - [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide -- [Unit tests](Unit tests) -- [GnuPG signature](GnuPG signature) for tags/releases +- [Unit tests](Unit-tests) +- Javascript linting - Shaarli uses [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript). +Run `make eslint` to check JS style. +- [GnuPG signature](GnuPG-signature) for tags/releases diff --git a/doc/md/Directory-structure.md b/doc/md/Directory-structure.md index 937a076..c0b4939 100644 --- a/doc/md/Directory-structure.md +++ b/doc/md/Directory-structure.md @@ -18,12 +18,18 @@ Here is the directory structure of Shaarli and the purpose of the different file ├── utils # utilities to ease testing │ └── ReferenceLinkDB.php └── UtilsTest.php + assets/ + ├── common/ # Assets shared by multiple themes + ├── ... + ├── default/ # Assets for the default template, before compilation + ├── fonts/ # Font files + ├── img/ # Images used by the default theme + ├── js/ # JavaScript files in ES6 syntax + ├── scss/ # SASS files + └── vintage/ # Assets for the vintage template, before compilation + └── ... COPYING # Shaarli license inc/ # static assets and 3rd party libraries - ├── awesomplete.* # tags autocompletion library - ├── blazy.* # picture wall lazy image loading library - ├── shaarli.css, reset.css # Shaarli stylesheet. - ├── qr.* # qr code generation library └── rain.tpl.class.php # RainTPL templating library images/ # Images and icons used in Shaarli data/ # data storage: bookmark database, configuration, logs, banlist... @@ -33,6 +39,13 @@ Here is the directory structure of Shaarli and the purpose of the different file ├── lastupdatecheck.txt # Update check timestamp file └── log.txt # login/IPban log. tpl/ # RainTPL templates for Shaarli. They are used to build the pages. + ├── default/ # Default Shaarli theme + ├── fonts/ # Font files + ├── img/ # Images + ├── js/ # JavaScript files compiled by Babel and compatible with all browsers + ├── css/ # CSS files compiled with SASS + └── vintage/ # Legacy Shaarli theme + └── ... cache/ # thumbnails cache # This directory is automatically created. You can erase it anytime you want. tmp/ # Temporary directory for compiled RainTPL templates. diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md index 05f0c8f..20138f4 100644 --- a/doc/md/Download-and-Installation.md +++ b/doc/md/Download-and-Installation.md @@ -38,12 +38,14 @@ $ mv Shaarli /path/to/shaarli/ Cloning using `git` or downloading Github branches as zip files requires additional steps: * Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies. + * Install [yarn](https://yarnpkg.com/lang/en/docs/install/) to build the frontend dependencies. * Install [python3-virtualenv](https://pypi.python.org/pypi/virtualenv) to build the local HTML documentation. ``` $ mkdir -p /path/to/shaarli && cd /path/to/shaarli/ $ git clone -b latest https://github.com/shaarli/Shaarli.git . $ composer install --no-dev --prefer-dist +$ make build_frontend $ make translate $ make htmldoc ``` @@ -91,7 +93,9 @@ $ composer install --no-dev --prefer-dist _Use at your own risk!_ -Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies. +Install [Composer](Unit-tests.md#install_composer) to manage Shaarli PHP dependencies, +and [yarn](https://yarnpkg.com/lang/en/docs/install/) +for front-end dependencies. To get the latest changes from the `master` branch: @@ -101,6 +105,7 @@ $ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/ # install/update third-party dependencies $ cd /path/to/shaarli $ composer install --no-dev --prefer-dist +$ make build_frontend $ make translate $ make htmldoc ``` diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md index ac24ff3..451ca36 100644 --- a/doc/md/Upgrade-and-migration.md +++ b/doc/md/Upgrade-and-migration.md @@ -83,6 +83,13 @@ $ make translate If you use translations in gettext mode, reload your web server. +Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install +[yarn](https://yarnpkg.com/lang/en/docs/install/): + +```bash +$ make build_frontend +``` + ### Migrating and upgrading from Sebsauvage's repository If you have installed Shaarli from [Sebsauvage's original Git repository](https://github.com/sebsauvage/Shaarli), you can use [Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to update your working copy. @@ -170,6 +177,13 @@ $ make translate If you use translations in gettext mode, reload your web server. +Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install +[yarn](https://yarnpkg.com/lang/en/docs/install/): + +```bash +$ make build_frontend +``` + Optionally, you can delete information related to the legacy version: ```bash