Merge pull request #1063 from PrivateBin/restructure-doc

Restructure documentation

Makefile

@@ -2,7 +2,7 @@
 
 CURRENT_VERSION = 1.5.2
 VERSION ?= 1.5.3
-VERSION_FILES = index.php bin/ cfg/ *.md css/ i18n/ img/ js/package.json js/privatebin.js lib/ Makefile tpl/ tst/
+VERSION_FILES = index.php bin/ cfg/ *.md doc/Installation.md css/ i18n/ img/ js/package.json js/privatebin.js lib/ Makefile tpl/ tst/
 REGEX_CURRENT_VERSION := $(shell echo $(CURRENT_VERSION) | sed "s/\./\\\./g")
 REGEX_VERSION := $(shell echo $(VERSION) | sed "s/\./\\\./g")
 

README.md

@@ -96,7 +96,7 @@ file](https://github.com/PrivateBin/PrivateBin/wiki/Configuration):
 
 * [FAQ](https://github.com/PrivateBin/PrivateBin/wiki/FAQ)
 
-* [Installation guide](https://github.com/PrivateBin/PrivateBin/blob/master/INSTALL.md#installation)
+* [Installation guide](https://github.com/PrivateBin/PrivateBin/blob/master/doc/Installation.md#installation)
 
 * [Configuration guide](https://github.com/PrivateBin/PrivateBin/wiki/Configuration)
 

doc/Generating Source Code Documentation.md

@@ -0,0 +1,59 @@
+# Generating Source Code Documentation
+
+## Generating PHP documentation
+
+In order to generate the documentation, you will need to install the following
+packages and its dependencies:
+* phpdoc
+* graphviz
+
+Details about
+[installing phpDocumentor](https://phpdoc.org/docs/latest/getting-started/installing.html)
+can be found in that projects documentation.
+
+Example for Debian and Ubuntu:
+```console
+$ sudo apt install php-pear graphviz
+$ sudo pear channel-discover pear.phpdoc.org
+$ sudo pear install phpdoc/phpDocumentor
+```
+
+To generate the documentation, change into the main directory and run phpdoc:
+```console
+$ cd PrivateBin
+$ phpdoc --visibility public,protected,private -t doc/phpdoc -d lib/
+```
+
+**Note:** When used with PHP 7, the prerelease of phpDocumentator 2.9 needs to be
+manually installed by downloading it from
+[GitHub](https://github.com/phpDocumentor/phpDocumentor2/releases/download/v2.9.0/phpDocumentor.phar)
+and then manually moving it to e.g. `/usr/local/bin` and making it executable.
+
+## Generating JS documentation
+
+In order to generate the documentation, you will need to install the following
+packages and its dependencies:
+* npm
+
+Then you can use the node package manager to install the latest stable release
+of jsdoc globally:
+
+```console
+$ npm install -g jsdoc
+```
+
+Example for Debian and Ubuntu, including steps to allow current user to install
+node modules globally:
+```console
+$ sudo apt install npm
+$ sudo mkdir /usr/local/lib/node_modules
+$ sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
+$ npm install -g jsdoc
+$ ln -s /usr/bin/nodejs /usr/local/bin/node
+```
+
+To generate the documentation, change into the main directory and run phpdoc:
+```console
+$ cd PrivateBin
+$ jsdoc -p -d doc/jsdoc js/privatebin.js js/legacy.js
+```

doc/Installation.md

@@ -1,6 +1,8 @@
 # Installation
 
-**TL;DR:** Download the
+## TL;DR
+
+Download the
 [latest release archive](https://github.com/PrivateBin/PrivateBin/releases/latest)
 (with the link labelled as "Source code (…)") and extract it in your web hosts
 folder where you want to install your PrivateBin instance. We try to provide a

doc/README.md

@@ -1,60 +1,37 @@
-Generating PHP documentation
+# PrivateBin Documentation
-============================
 
-In order to generate the documentation, you will need to install the following
+## [Frequently Asked Questions](https://github.com/PrivateBin/PrivateBin/wiki/FAQ)
-packages and its dependencies:
-* phpdoc
-* graphviz
 
-Details about
+Please have a look at these questions *before* opening an issue in this repo.
-[installing phpDocumentor](https://phpdoc.org/docs/latest/getting-started/installing.html)
-can be found in that projects documentation.
 
-Example for Debian and Ubuntu:
+## [Installation guide](https://github.com/PrivateBin/PrivateBin/blob/master/doc/Installation.md#installation)
-```console
-$ sudo apt install php-pear graphviz
-$ sudo pear channel-discover pear.phpdoc.org
-$ sudo pear install phpdoc/phpDocumentor
-```
 
-To generate the documentation, change into the main directory and run phpdoc:
+Minimal requirements, hardening and securing your installation and initial
-```console
+configuration.
-$ cd PrivateBin
-$ phpdoc --visibility public,protected,private -t doc/phpdoc -d lib/
-```
 
-**Note:** When used with PHP 7, the prerelease of phpDocumentator 2.9 needs to be
+## [Configuration guide](https://github.com/PrivateBin/PrivateBin/wiki/Configuration)
-manually installed by downloading it from
-[GitHub](https://github.com/phpDocumentor/phpDocumentor2/releases/download/v2.9.0/phpDocumentor.phar)
-and then manually moving it to e.g. `/usr/local/bin` and making it executable.
 
-Generating JS documentation
+Detailed guide on each configuration option and their effects.
-============================
 
-In order to generate the documentation, you will need to install the following
+## [Templates](https://github.com/PrivateBin/PrivateBin/wiki/Templates)
-packages and its dependencies:
-* npm
 
-Then you can use the node package manager to install the latest stable release
+How to change an existing template or create your own, as well as an overview of
-of jsdoc globally:
+the currently included templates.
 
-```console
+## [Translation guide](https://github.com/PrivateBin/PrivateBin/wiki/Translation)
-$ npm install -g jsdoc
-```
 
-Example for Debian and Ubuntu, including steps to allow current user to install
+How to help translate PrivateBin and technical background on it's implementation.
-node modules globally:
-```console
-$ sudo apt install npm
-$ sudo mkdir /usr/local/lib/node_modules
-$ sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
-$ npm install -g jsdoc
-$ ln -s /usr/bin/nodejs /usr/local/bin/node
-```
 
-To generate the documentation, change into the main directory and run phpdoc:
+## [Developer guide](https://github.com/PrivateBin/PrivateBin/wiki/Development)
-```console
-$ cd PrivateBin
-$ jsdoc -p -d doc/jsdoc js/privatebin.js js/legacy.js
-```
 
+Know how for participating in PrivateBins development.
+
+### [Generating Source Code Documentation](https://github.com/PrivateBin/PrivateBin/blob/master/doc/Generating%20Source%20Code%20Documentation.md#generating-source-code-documentation)
+
+How to generate the source code API documentation, as found on the project
+website for [PHP](https://privatebin.info/codedoc/) and [JS](https://privatebin.info/jsdoc/)
+
+### [Running Unit Tests](https://github.com/PrivateBin/PrivateBin/blob/master/tst/README.md#running-all-unit-tests)
+
+How to run the PHP & JS unit tests, including a brief introduction to property
+based unit testing.

tst/README.md

@@ -1,5 +1,4 @@
-Running all unit tests
+# Running All Unit Tests
-======================
 
 Since it is non-trivial to setup all dependencies for our unit testing suite,
 we provide a docker image that bundles all of them into one container, both
@@ -34,8 +33,7 @@ well as the integrated unit testing utilities. See our [docker wiki
 page](https://github.com/PrivateBin/PrivateBin/wiki/Docker#janitor-image-with-cloud9-and-theia-webide-janitortechnologyprivatebin)
 for further details on this.
 
-Running PHP unit tests
+## Running PHP Unit Tests
-======================
 
 In order to run these tests, you will need to install the following packages
 and their dependencies:
@@ -75,8 +73,7 @@ $ phpunit ConfigurationCombinationsTest.php
 Note that it can take an hour or longer to run the several thousand tests.
 
 
-Running JavaScript unit tests
+## Running JavaScript Unit Tests
-=============================
 
 In order to run these tests, you will need to install the following packages
 and its dependencies:
@@ -112,8 +109,7 @@ $ cd PrivateBin/js
 $ nyc mocha
 ```
 
-Property based unit testing
+### Property Based Unit Testing
----------------------------
 
 In the JavaScript unit tests we use the JSVerify library to leverage property
 based unit testing. Instead of artificially creating specific test cases to
@@ -154,4 +150,3 @@ with the same RNG state as follows:
 ```console
 $ nyc mocha test --jsverifyRngState 88caf85079d32e416b
 ```
-