Merge pull request #1063 from PrivateBin/restructure-doc
Restructure documentation
This commit is contained in:
El RIDO
GitHub
commit
3513d18029
6 changed files with 93 additions and 60 deletions
2
Makefile
2
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")
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
59
doc/Generating Source Code Documentation.md
Normal file
59
doc/Generating Source Code Documentation.md
Normal file
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue