diff --git a/Makefile b/Makefile index a1e29a9c..d94a0a95 100644 --- a/Makefile +++ b/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") diff --git a/README.md b/README.md index 70730f34..c14259ce 100644 --- a/README.md +++ b/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) diff --git a/doc/Generating Source Code Documentation.md b/doc/Generating Source Code Documentation.md new file mode 100644 index 00000000..0e9f1e0a --- /dev/null +++ b/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 +``` diff --git a/INSTALL.md b/doc/Installation.md similarity index 99% rename from INSTALL.md rename to doc/Installation.md index e30c0519..5319414d 100644 --- a/INSTALL.md +++ b/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 diff --git a/doc/README.md b/doc/README.md index d513ca34..9bb7c77d 100644 --- a/doc/README.md +++ b/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 -packages and its dependencies: -* phpdoc -* graphviz +## [Frequently Asked Questions](https://github.com/PrivateBin/PrivateBin/wiki/FAQ) -Details about -[installing phpDocumentor](https://phpdoc.org/docs/latest/getting-started/installing.html) -can be found in that projects documentation. +Please have a look at these questions *before* opening an issue in this repo. -Example for Debian and Ubuntu: -```console -$ sudo apt install php-pear graphviz -$ sudo pear channel-discover pear.phpdoc.org -$ sudo pear install phpdoc/phpDocumentor -``` +## [Installation guide](https://github.com/PrivateBin/PrivateBin/blob/master/doc/Installation.md#installation) -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/ -``` +Minimal requirements, hardening and securing your installation and initial +configuration. -**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. +## [Configuration guide](https://github.com/PrivateBin/PrivateBin/wiki/Configuration) -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 -packages and its dependencies: -* npm +## [Templates](https://github.com/PrivateBin/PrivateBin/wiki/Templates) -Then you can use the node package manager to install the latest stable release -of jsdoc globally: +How to change an existing template or create your own, as well as an overview of +the currently included templates. -```console -$ npm install -g jsdoc -``` +## [Translation guide](https://github.com/PrivateBin/PrivateBin/wiki/Translation) -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 -``` +How to help translate PrivateBin and technical background on it's implementation. -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 -``` +## [Developer guide](https://github.com/PrivateBin/PrivateBin/wiki/Development) +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. \ No newline at end of file diff --git a/tst/README.md b/tst/README.md index c8bb7519..db310e9b 100644 --- a/tst/README.md +++ b/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 ``` -