aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md
diff options
context:
space:
mode:
authorArthurHoaro <arthur@hoa.ro>2018-03-28 19:08:06 +0200
committerGitHub <noreply@github.com>2018-03-28 19:08:06 +0200
commitc81f1afc0a3a16daf98741a63c7524b27835da99 (patch)
treedfe81b73f028dfc27eda916b14bf4bc17966b082 /doc/md
parent9b2bd66fb60ffd5a833480bf329062c7d57bc8c4 (diff)
parentd7eb06bd7c4d01bbdf67f4f100af7a3e300098d3 (diff)
downloadShaarli-c81f1afc0a3a16daf98741a63c7524b27835da99.tar.gz
Shaarli-c81f1afc0a3a16daf98741a63c7524b27835da99.tar.zst
Shaarli-c81f1afc0a3a16daf98741a63c7524b27835da99.zip
Merge pull request #1072 from ArthurHoaro/feature/modern-front-end
Manage frontend dependencies with npm/yarn and webpack
Diffstat (limited to 'doc/md')
-rw-r--r--doc/md/Continuous-integration-tools.md7
-rw-r--r--doc/md/Development-guidelines.md9
-rw-r--r--doc/md/Directory-structure.md21
-rw-r--r--doc/md/Download-and-Installation.md7
-rw-r--r--doc/md/Upgrade-and-migration.md14
5 files changed, 47 insertions, 11 deletions
diff --git a/doc/md/Continuous-integration-tools.md b/doc/md/Continuous-integration-tools.md
index 4bd7a0ba..4ca6bdc7 100644
--- a/doc/md/Continuous-integration-tools.md
+++ b/doc/md/Continuous-integration-tools.md
@@ -2,8 +2,8 @@
2A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations: 2A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations:
3 3
4- Documentation - generate a local HTML copy of the GitHub wiki 4- Documentation - generate a local HTML copy of the GitHub wiki
5- [Static analysis](Static analysis) - check that the code is compliant to PHP conventions 5- [Static analysis](Static-analysis) - check that the code is compliant to PHP conventions
6- [Unit tests](Unit tests) - ensure there are no regressions introduced by new commits 6- [Unit tests](Unit-tests) - ensure there are no regressions introduced by new commits
7 7
8## Automatic builds 8## Automatic builds
9[Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build: 9[Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build:
@@ -17,7 +17,8 @@ Each build job:
17 17
18- updates Composer 18- updates Composer
19- installs 3rd-party test dependencies with Composer 19- installs 3rd-party test dependencies with Composer
20- runs [Unit tests](Unit tests) 20- runs [Unit tests](Unit-tests)
21- runs ESLint check
21 22
22After all jobs have finished, Travis returns the results to GitHub: 23After all jobs have finished, Travis returns the results to GitHub:
23 24
diff --git a/doc/md/Development-guidelines.md b/doc/md/Development-guidelines.md
index 532ec2e4..46b7c6f8 100644
--- a/doc/md/Development-guidelines.md
+++ b/doc/md/Development-guidelines.md
@@ -3,8 +3,11 @@
3Please have a look at the following pages: 3Please have a look at the following pages:
4 4
5- [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md) 5- [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md)
6- [Static analysis](Static analysis) - patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially: 6- [Static analysis](Static-analysis) - patches should try to stick to the
7[PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially:
7 - [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard 8 - [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard
8 - [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide 9 - [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide
9- [Unit tests](Unit tests) 10- [Unit tests](Unit-tests)
10- [GnuPG signature](GnuPG signature) for tags/releases 11- Javascript linting - Shaarli uses [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript).
12Run `make eslint` to check JS style.
13- [GnuPG signature](GnuPG-signature) for tags/releases
diff --git a/doc/md/Directory-structure.md b/doc/md/Directory-structure.md
index 937a076d..c0b49393 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
18 ├── utils # utilities to ease testing 18 ├── utils # utilities to ease testing
19 │ └── ReferenceLinkDB.php 19 │ └── ReferenceLinkDB.php
20 └── UtilsTest.php 20 └── UtilsTest.php
21 assets/
22 ├── common/ # Assets shared by multiple themes
23 ├── ...
24 ├── default/ # Assets for the default template, before compilation
25 ├── fonts/ # Font files
26 ├── img/ # Images used by the default theme
27 ├── js/ # JavaScript files in ES6 syntax
28 ├── scss/ # SASS files
29 └── vintage/ # Assets for the vintage template, before compilation
30 └── ...
21 COPYING # Shaarli license 31 COPYING # Shaarli license
22 inc/ # static assets and 3rd party libraries 32 inc/ # static assets and 3rd party libraries
23 ├── awesomplete.* # tags autocompletion library
24 ├── blazy.* # picture wall lazy image loading library
25 ├── shaarli.css, reset.css # Shaarli stylesheet.
26 ├── qr.* # qr code generation library
27 └── rain.tpl.class.php # RainTPL templating library 33 └── rain.tpl.class.php # RainTPL templating library
28 images/ # Images and icons used in Shaarli 34 images/ # Images and icons used in Shaarli
29 data/ # data storage: bookmark database, configuration, logs, banlist... 35 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
33 ├── lastupdatecheck.txt # Update check timestamp file 39 ├── lastupdatecheck.txt # Update check timestamp file
34 └── log.txt # login/IPban log. 40 └── log.txt # login/IPban log.
35 tpl/ # RainTPL templates for Shaarli. They are used to build the pages. 41 tpl/ # RainTPL templates for Shaarli. They are used to build the pages.
42 ├── default/ # Default Shaarli theme
43 ├── fonts/ # Font files
44 ├── img/ # Images
45 ├── js/ # JavaScript files compiled by Babel and compatible with all browsers
46 ├── css/ # CSS files compiled with SASS
47 └── vintage/ # Legacy Shaarli theme
48 └── ...
36 cache/ # thumbnails cache 49 cache/ # thumbnails cache
37 # This directory is automatically created. You can erase it anytime you want. 50 # This directory is automatically created. You can erase it anytime you want.
38 tmp/ # Temporary directory for compiled RainTPL templates. 51 tmp/ # Temporary directory for compiled RainTPL templates.
diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md
index 05f0c8f2..20138f49 100644
--- a/doc/md/Download-and-Installation.md
+++ b/doc/md/Download-and-Installation.md
@@ -38,12 +38,14 @@ $ mv Shaarli /path/to/shaarli/
38Cloning using `git` or downloading Github branches as zip files requires additional steps: 38Cloning using `git` or downloading Github branches as zip files requires additional steps:
39 39
40 * Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies. 40 * Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies.
41 * Install [yarn](https://yarnpkg.com/lang/en/docs/install/) to build the frontend dependencies.
41 * Install [python3-virtualenv](https://pypi.python.org/pypi/virtualenv) to build the local HTML documentation. 42 * Install [python3-virtualenv](https://pypi.python.org/pypi/virtualenv) to build the local HTML documentation.
42 43
43``` 44```
44$ mkdir -p /path/to/shaarli && cd /path/to/shaarli/ 45$ mkdir -p /path/to/shaarli && cd /path/to/shaarli/
45$ git clone -b latest https://github.com/shaarli/Shaarli.git . 46$ git clone -b latest https://github.com/shaarli/Shaarli.git .
46$ composer install --no-dev --prefer-dist 47$ composer install --no-dev --prefer-dist
48$ make build_frontend
47$ make translate 49$ make translate
48$ make htmldoc 50$ make htmldoc
49``` 51```
@@ -91,7 +93,9 @@ $ composer install --no-dev --prefer-dist
91 93
92_Use at your own risk!_ 94_Use at your own risk!_
93 95
94Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies. 96Install [Composer](Unit-tests.md#install_composer) to manage Shaarli PHP dependencies,
97and [yarn](https://yarnpkg.com/lang/en/docs/install/)
98for front-end dependencies.
95 99
96To get the latest changes from the `master` branch: 100To get the latest changes from the `master` branch:
97 101
@@ -101,6 +105,7 @@ $ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
101# install/update third-party dependencies 105# install/update third-party dependencies
102$ cd /path/to/shaarli 106$ cd /path/to/shaarli
103$ composer install --no-dev --prefer-dist 107$ composer install --no-dev --prefer-dist
108$ make build_frontend
104$ make translate 109$ make translate
105$ make htmldoc 110$ make htmldoc
106``` 111```
diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md
index ac24ff34..451ca36d 100644
--- a/doc/md/Upgrade-and-migration.md
+++ b/doc/md/Upgrade-and-migration.md
@@ -83,6 +83,13 @@ $ make translate
83 83
84If you use translations in gettext mode, reload your web server. 84If you use translations in gettext mode, reload your web server.
85 85
86Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install
87[yarn](https://yarnpkg.com/lang/en/docs/install/):
88
89```bash
90$ make build_frontend
91```
92
86### Migrating and upgrading from Sebsauvage's repository 93### Migrating and upgrading from Sebsauvage's repository
87 94
88If 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. 95If 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
170 177
171If you use translations in gettext mode, reload your web server. 178If you use translations in gettext mode, reload your web server.
172 179
180Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install
181[yarn](https://yarnpkg.com/lang/en/docs/install/):
182
183```bash
184$ make build_frontend
185```
186
173Optionally, you can delete information related to the legacy version: 187Optionally, you can delete information related to the legacy version:
174 188
175```bash 189```bash