From 76c3a4dbed11b9a5df2437db00e96608244bd693 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sat, 18 Nov 2017 16:22:43 +0100 Subject: 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) --- Makefile | 11 ----------- doc/md/Download-and-Installation.md | 32 ++++++++++++++++++++++---------- doc/md/Unit-tests.md | 10 ++++++---- 3 files changed, 28 insertions(+), 25 deletions(-) diff --git a/Makefile b/Makefile index c2d55946..d659d908 100644 --- 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 be848c97..e64d1a43 100644 --- 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 d200634f..f6030d5c 100644 --- 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 -- cgit v1.2.3