Jsdoc support (#527)

* JSDoc support

* update .gitignore for nodejs project + custom rules
* add JSDoc config file .jsdoc.json
* update README to explain how to build the documentation
* update package.json with JSDoc and its minami theme

* fix unused JSDoc themes

* + wrap the command for doc building
+ modify the doc
+ sort scripts in alphabetical order

.gitignore

@@ -1,8 +1,79 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Typescript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+
+# macOS custom attributes
 .DS_Store
+
+# VisualStudio
 .vscode
-/config.js
-/node_modules
-/npm-debug.log
-/server/db
-/server/assets
-/server/temp
+
+# Personnal flood config
+config.js
+
+# flood server
+server/db
+server/assets
+server/temp
+
+# Vim temp files
+*.swp
+
+# JSDoc output
+docs/
+out/

.jsdoc.json

@@ -0,0 +1,27 @@
+{
+    "tags": {
+        "allowUnknownTags": true,
+        "dictionaries": ["jsdoc"]
+    },
+    "source": {
+        "include": ["client", "server", "shared", "package.json", "README.md"],
+        "includePattern": ".js$",
+        "excludePattern": "(node_modules/|docs)"
+    },
+    "plugins": [
+        "plugins/markdown"
+    ],
+    "templates": {
+        "cleverLinks": false,
+        "monospaceLinks": true,
+        "useLongnameInNav": false,
+        "showInheritedInNav": true
+    },
+    "opts": {
+        "destination": "./docs/",
+        "encoding": "utf8",
+        "private": true,
+        "recurse": true,
+        "template": "./node_modules/minami"
+    }
+}

README.md

@@ -9,9 +9,11 @@ Flood is another web interface for [rtorrent](https://github.com/rakshasa/rtorre
 It's a work-in-progress, and it might not have all of the features you want (yet). However, new features are added frequently. Feel free to file an issue and I'll try to prioritize your feature requests.
 
 #### Feedback
+
 If you have a specific issue or bug, please file a Github issue. If you want to participate in discussions about Flood's future, please join the [Flood Discord server](https://discord.gg/Z7yR5Uf).
 
 # Usage
+
 #### Pre-Requisites
 
 1. [rTorrent](https://github.com/rakshasa/rtorrent) needs to be installed __with XMLRPC__ configuration. _If you are currently using a web UI for rTorrent, you've already done this._
@@ -34,6 +36,7 @@ If you have a specific issue or bug, please file a Github issue. If you want to
   * For example, if hosting Flood from `https://foo.bar/apps/flood`, you would set `baseURI` to `/apps/flood`. If hosting flood from `https://foo.bar`, you do not need to configure `baseURI`.
 
 #### Compiling assets and starting the server
+
 1. Run `npm install`.
   * Note: Since #523 [node-gyp](https://www.npmjs.com/package/node-gyp) is needed. **IF** you need `sudo`, use `sudo npm i --unsafe-perm` (see [here](https://github.com/nodejs/node-gyp/issues/454) for why `--unsafe-perm`) else installation will fail. If you dont need sudo just use `npm i` as usual.
   * If your system use python3 as default you will need to install python2 and use `npm i --python="/usr/bin/python2"`.
@@ -44,6 +47,7 @@ If you have a specific issue or bug, please file a Github issue. If you want to
 1. Upon loading the UI the first time, you will be prompted to create a user account.
 
 #### Updating
+
 1. To update, run `git pull` in this repository's directory.
 1. Check `config.template.js` for configuration changes that you may wish to incoporate in your `config.js`.
 1. Kill the running Node server.
@@ -52,15 +56,18 @@ If you have a specific issue or bug, please file a Github issue. If you want to
 1. Restart it with `npm start`.
 
 #### Tips
+
 * I run the web server with `screen` to keep the web server running independently of the terminal session.
 * Ubuntu users may need to install `nodejs-legacy` (`sudo apt-get install nodejs-legacy`) for dependencies to install successfully. You can read more on [this Stack Overflow post](http://stackoverflow.com/questions/21168141/cannot-install-packages-using-node-package-manager-in-ubuntu).
 
 #### Local Development
+
 1. Run `npm install`.
 2. Run `npm run start:development:server` and `npm run start:development:client` in separate terminal instances.
   * `npm run start:development:server` uses [nodemon](https://github.com/remy/nodemon) to watch for changes to the server-side JavaScript.
   * `npm run start:development:client` watches for changes in the client-side source.
 3. Access the UI through the [WebpackDevServer](https://webpack.js.org/configuration/dev-server/). It expects to proxy requests to the Flood server you have running, defined in `config.js` as `floodServerProxy`.
+4. Build the documentation `npm run build-docs`.
 
 #### Environment Variables
 
@@ -69,6 +76,7 @@ If you have a specific issue or bug, please file a Github issue. If you want to
 1. `DEV_SERVER_HTTPS`: webpackDevServer's protocol, used when developing Flood. Defaults to `http`.
 
 #### Running with Docker
+
 1. `docker build -t rtorrent-flood .`
 2. `docker run --name rtorrent-flood -e RTORRENT_SCGI_HOST=w.x.y.z -p 3000:3000 rtorrent-flood`
 3. Other supported environment variables:
@@ -86,6 +94,7 @@ The docker container includes a volume at `/data`, which is where the database w
 This project's client-side build tooling is based on the wonderful [create-react-app](https://github.com/facebookincubator/create-react-app).
 
 # Screenshots
+
 ![](https://s3.amazonaws.com/johnfurrow.com/share/flood-screenshots-a.png)
 ![](https://s3.amazonaws.com/johnfurrow.com/share/flood-screenshots-b.png)
 ![](https://s3.amazonaws.com/johnfurrow.com/share/flood-screenshots-c.png)

package.json

@@ -4,16 +4,17 @@
   "private": true,
   "scripts": {
     "build": "node client/scripts/build.js",
-    "test": "node client/scripts/test.js --env=jsdom",
     "build-assets": "UPDATED_SCRIPT=build npm run deprecated-warning && npm run build",
-    "lint": "eslint .",
+    "build-docs": "./node_modules/.bin/jsdoc -c ./.jsdoc.json",
     "deprecated-warning": "node client/scripts/deprecated-warning.js && sleep 10",
-    "start:development:server": "NODE_ENV=development nodemon server/bin/start.js",
+    "lint": "eslint .",
+    "start": "node server/bin/start.js",
     "start:development": "UPDATED_SCRIPT=start:development:server npm run deprecated-warning && npm run start:development:server",
+    "start:development:client": "node client/scripts/start.js",
+    "start:development:server": "NODE_ENV=development nodemon server/bin/start.js",
     "start:production": "UPDATED_SCRIPT=start npm run deprecated-warning && npm start",
-    "start": "node server/bin/start.js",
     "start:watch": "UPDATED_SCRIPT=start:development:client npm run deprecated-warning && npm run start:development:client",
-    "start:development:client": "node client/scripts/start.js"
+    "test": "node client/scripts/test.js --env=jsdom"
   },
   "dependencies": {
     "argon2": "^0.16.2",
@@ -111,6 +112,8 @@
     "eslint-plugin-jsx-a11y": "^5.1.1",
     "eslint-plugin-react": "7.1.0",
     "jest": "20.0.4",
+    "jsdoc": "~3.5.5",
+    "minami": "^1.2.3",
     "nodemon": "^1.8.1",
     "source-map-loader": "^0.2.1",
     "webpack-dev-server": "^2.6.1",