documentation cleanup

 * In preparation of #930 work
 * Remove/reorder duplicate documentation from Makefile/Unit-tests.md/Download-and-Installation.md (composer information is now in Unit-tests.md)
 * Installation using git: add composer requirement to all git installation procedures, add python3-virtualenv requirement
 * Styling (horizontal rulers, spacing, descriptive headers)

diff --git a/Makefile b/Makefile
index c2d5594605943f87e16da7dee295acfff5e074ab..d659d908e45aad561638d8f7617b30b3ed51c35a 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -1,17 +1,6 @@
 # The personal, minimalist, super-fast, database free, bookmarking service.
 # Makefile for PHP code analysis & testing, documentation and release generation
 
-# Prerequisites:
-# - install Composer, either:
-#   - from your distro's package manager;
-#   - from the official website (https://getcomposer.org/download/);
-# - install/update test dependencies:
-#   $ composer install  # 1st setup
-#   $ composer update
-# - install Xdebug for PHPUnit code coverage reports:
-#   - see http://xdebug.org/docs/install
-#   - enable in php.ini
-
 BIN = vendor/bin
 PHP_SOURCE = index.php application tests plugins
 PHP_COMMA_SOURCE = index.php,application,tests,plugins

diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md
index be848c97e9ab44f8629b5ffbeb2ad69d82c67b31..e64d1a43e25b55c4d53e64579e625335eb02b2b4 100644 (file)
--- a/doc/md/Download-and-Installation.md
+++ b/doc/md/Download-and-Installation.md
@@ -17,40 +17,44 @@ Using one of the following methods:
 - by cloning the Git repository
 - using Docker: [see the documentation](docker/shaarli-images)
 
----
+--------------------------------------------------------------------------------
 
 ## Latest release (recommended)
+
 ### Download as an archive
-Get the latest released version from the [releases](https://github.com/shaarli/Shaarli/releases) page.
 
-**Download our *shaarli-full* archive** to include dependencies.
+In most cases, you should download the latest Shaarli release from the [releases](https://github.com/shaarli/Shaarli/releases) page. **Download our *shaarli-full* archive** to include dependencies.
 
 The current latest released version is `v0.9.1`
 
-Or in command lines:
-
 ```bash
 $ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.1/shaarli-v0.9.1-full.zip
 $ unzip shaarli-v0.9.1-full.zip
 $ mv Shaarli /path/to/shaarli/
 ```
 
-In most cases, download Shaarli from the [releases](https://github.com/shaarli/Shaarli/releases) page. 
-Cloning using `git` or downloading Github branches as zip files requires additional steps (see below).
-
 ### Using git
 
+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 [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 translate
+$ make htmldoc
 ```
 
+--------------------------------------------------------------------------------
+
 ## Stable version
 
 The stable version has been experienced by Shaarli users, and will receive security updates.
 
+
 ### Download as an archive
 
 As a .zip archive:
@@ -69,9 +73,9 @@ $ tar xvf stable.tar.gz
 $ mv Shaarli-stable /path/to/shaarli/
 ```
 
-### Clone with Git 
+### Using git
 
-[Composer](https://getcomposer.org/) is required to build a functional Shaarli installation when pulling from git.
+Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies.
 
 ```bash
 $ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/
@@ -80,10 +84,15 @@ $ cd /path/to/shaarli/
 $ composer install --no-dev --prefer-dist
 ```
 
+
+--------------------------------------------------------------------------------
+
 ## Development version (mainline)
 
 _Use at your own risk!_
 
+Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies.
+
 To get the latest changes from the `master` branch:
 
 ```bash
@@ -93,8 +102,11 @@ $ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
 $ cd /path/to/shaarli
 $ composer install --no-dev --prefer-dist
 $ make translate
+$ make htmldoc
 ```
 
+-------------------------------------------------------------------------------
+
 ## Finish Installation
 
 Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.

diff --git a/doc/md/Unit-tests.md b/doc/md/Unit-tests.md
index d200634f6ea6513ff5094abc7971e0752cd2b543..f6030d5c2f6134848b58ed8987f1458c8dd4df23 100644 (file)
--- a/doc/md/Unit-tests.md
+++ b/doc/md/Unit-tests.md
@@ -2,12 +2,12 @@
 
 The framework used is [PHPUnit](https://phpunit.de/); it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool.
 
-Regarding Composer, you can either use:
+### Install composer
 
-- a system-wide version, e.g. installed through your distro's package manager
-- a local version, downloadable [here](https://getcomposer.org/download/)
+You can either use:
 
-#### Sample usage
+- a system-wide version, e.g. installed through your distro's package manager
+- a local version, downloadable [here](https://getcomposer.org/download/).
 
 ```bash
 # system-wide version
@@ -29,6 +29,8 @@ $ composer update
 
 #### Install and enable Xdebug to generate PHPUnit coverage reports
 
+See http://xdebug.org/docs/install
+
 For Debian-based distros:
 ```bash
 $ aptitude install php5-xdebug