StarMirror
/
PrivateBin
mirror of https://github.com/PrivateBin/PrivateBin
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #1063 from PrivateBin/restructure-doc 

Restructure documentation
pull/1140/head
El RIDO 2023-08-08 20:24:20 +02:00 committed by GitHub
parent e83f51b547 be6eadd7c6
commit 3513d18029
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 93 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Makefile
View File

@ -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")

2
README.md
View File

@ -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
View 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
```

4
INSTALL.md → doc/Installation.md
View File

@ -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

73
doc/README.md
View File

@ -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.

13
tst/README.md
View File

@ -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
```