Improved documentation

docs/.gitignore

@@ -1 +1,3 @@
 node_modules/
+package-lock.json
+_book/

docs/book.json

@@ -0,0 +1,3 @@
+{
+  "root": "docs/"
+}

docs/docs/README.md

@@ -0,0 +1,20 @@
+# Web Greeter for LightDM
+
+A modern, visually appealing greeter for LightDM, that allows to create web based themes with HTML, CSS and JavaScript.
+
+This is a try to update the [Antergos web-greeter](https://github.com/Antergos/web-greeter), following what they left.
+
+## Features
+
+- Create themes with HTML, CSS and JavaScript!
+- Should work everywhere.
+- JavaScript error handling, allowing to load the default theme.
+- Themes could be simple, or very complex.
+- Battery and brightness control.
+
+## Theme JavaScript API
+See the [JavaScript API][jsAPI] here, and some [HOWTO][howto] here too!
+
+
+[jsAPI]: ./api/LightDM.md
+[howto]: ./howto

docs/docs/SUMMARY.md

@@ -0,0 +1,18 @@
+# Summary
+
+* [Introduction](README.md)
+
+## Javascript API
+* [LightDM](api/LightDM.md)
+* [Greeter](api/Greeter.md)
+* [GreeterConfig](api/GreeterConfig.md)
+* [ThemeUtils](api/ThemeUtils.md)
+* [Battery](api/Battery.md)
+* [Language](api/Language.md)
+* [Layout](api/Layout.md)
+* [Session](api/Session.md)
+* [User](api/User.md)
+* [Signal](api/Signal.md)
+
+## HOWTO
+* [Introduction](howto/intro.md)

docs/docs/api/Battery.md

@@ -1,7 +1,7 @@
 <a id="LightDM.Battery"></a>
 
 ## LightDM.Battery
-Interface for object that holds info about the battery on the system. This object is not created by the theme's code, but rather by the [`LightDM.Greeter`](#dl-LightDM-Greeter) class.
+Interface for object that holds info about the battery on the system. This object is not created by the theme's code, but rather by the [`LightDM.Greeter`](Greeter.md) class.
 
 <a id="LightDM.Battery+level"></a>
 

docs/docs/api/Greeter.md

@@ -4,7 +4,7 @@
 Base class for the greeter's Theme JavaScript API. Greeter themes will interact
 directly with an object derived from this class to facilitate the user log-in process.
 The greeter will automatically create an instance when it starts.
-The instance can be accessed using the global variable: [`lightdm`](#dl-window-lightdm).
+The instance can be accessed using the global variable: `lightdm`.
 
 <a id="LightDM.Greeter+authentication_user"></a>
 
@@ -41,17 +41,7 @@ The battery data
 <a id="LightDM.Greeter+brightness"></a>
 
 ### greeter.brightness : <code>Number</code>
-Gets the brightness
+The display brightness
-
-<a id="LightDM.Greeter+brightness"></a>
-
-### greeter.brightness
-Sets the brightness
-
-
-| Param | Type | Description |
-| --- | --- | --- |
-| quantity | <code>Number</code> | The quantity to set |
 
 <a id="LightDM.Greeter+can_access_battery"></a>
 
@@ -230,7 +220,7 @@ Gets emitted when the greeter should show a message to the user.
 ### greeter.show\_prompt : <code>Signal</code>
 Gets emitted when the greeter should show a prompt to the user.
 
-<a id="LightDM.Greeter+authenticate"></a>
+<a name="LightDM.Greeter+authenticate"></a>
 
 ### greeter.authenticate(username)
 Starts the authentication procedure for a user.

docs/docs/api/GreeterConfig.md

@@ -4,7 +4,7 @@
 Provides greeter themes with a way to access values from the greeter's config
 file located at `/etc/lightdm/web-greeter.yml`. The greeter will
 create an instance of this class when it starts. The instance can be accessed
-with the global variable: [`greeter_config`](#dl-window-greeter_config).
+with the global variable: `greeter_config`.
 
 <a id="LightDM.GreeterConfig+branding"></a>
 
@@ -49,7 +49,7 @@ Holds keys/values from the `features` section of the config file.
 | --- | --- | --- |
 | battery | <code>Boolean</code> | Enable greeter and themes to ger battery status. |
 | backlight | <code>Object</code> |  |
-| enabled | <code>Boolean</code> | Enable greeter and themes to control display backlight. |
+| backlight.enabled | <code>Boolean</code> | Enable greeter and themes to control display backlight. |
-| value | <code>Number</code> | The amount to increase/decrease brightness by greeter. |
+| backlight.value | <code>Number</code> | The amount to increase/decrease brightness by greeter. |
-| steps | <code>Number</code> | How many steps are needed to do the change. |
+| backlight.steps | <code>Number</code> | How many steps are needed to do the change. |
 

docs/docs/api/Language.md

@@ -2,7 +2,7 @@
 
 ## LightDM.Language
 Interface for object that holds info about a language on the system. Language objects are not
-created by the theme's code, but rather by the [`LightDM.Greeter`](#dl-LightDM-Greeter) class.
+created by the theme's code, but rather by the [`LightDM.Greeter`](Greeter.md) class.
 
 <a id="LightDM.Language+code"></a>
 

docs/docs/api/Layout.md

@@ -2,7 +2,7 @@
 
 ## LightDM.Layout
 Interface for object that holds info about a keyboard layout on the system. Language
-objects are not created by the theme's code, but rather by the [`LightDM.Greeter`](#dl-LightDM-Greeter) class.
+objects are not created by the theme's code, but rather by the [`LightDM.Greeter`](Greeter.md) class.
 
 <a id="LightDM.Layout+description"></a>
 

docs/docs/api/LightDM.md

@@ -0,0 +1,6 @@
+<a id="LightDM"></a>
+
+## LightDM : <code>object</code>
+The greeter's Theme JavaScript API.
+Accesible through `lightdm` global variable.
+

docs/docs/api/Session.md

@@ -2,7 +2,7 @@
 
 ## LightDM.Session
 Interface for object that holds info about a session. Session objects are not
-created by the theme's code, but rather by the [`LightDM.Greeter`](#dl-LightDM-Greeter) class.
+created by the theme's code, but rather by the [`LightDM.Greeter`](Greeter.md) class.
 
 <a id="LightDM.Session+name"></a>
 

docs/docs/api/Signal.md

@@ -0,0 +1,26 @@
+<a id="LightDM.Signal"></a>
+
+## LightDM.Signal
+Interface for signals connected to LightDM itself. This is not created by the theme's code, but rather by Web Greeter.
+When Web Greeter triggers the signal, all calbacks are executed.
+
+<a id="LightDM.Signal+connect"></a>
+
+### signal.connect(callback)
+Connects a callback to the signal.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| callback | <code>function</code> | The callback to attach. |
+
+<a id="LightDM.Signal+disconnect"></a>
+
+### signal.disconnect(callback)
+Disconnects a callback to the signal.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| callback | <code>function</code> | The callback to disattach. |
+

docs/docs/api/ThemeUtils.md

@@ -3,7 +3,7 @@
 ## LightDM.ThemeUtils
 Provides various utility methods for use in greeter themes. The greeter will automatically
 create an instance of this class when it starts. The instance can be accessed
-with the global variable: [`theme_utils`](#dl-window-theme_utils).
+with the global variable: `theme_utils`.
 
 <a id="LightDM.ThemeUtils+bind_this"></a>
 

docs/docs/api/User.md

@@ -2,7 +2,7 @@
 
 ## LightDM.User
 Interface for object that holds info about a user account on the system. User
-objects are not created by the theme's code, but rather by the [`LightDM.Greeter`](#dl-LightDM-Greeter) class.
+objects are not created by the theme's code, but rather by the [`LightDM.Greeter`](Greeter.md) class.
 
 <a id="LightDM.User+display_name"></a>
 

docs/docs/howto/intro.md

@@ -0,0 +1,51 @@
+# Introduction
+
+Web Greeter has a simple API, documented here, which allows to communicate to the Web Greeter itself and the LightDM API.
+
+To create a theme, you will need these essential functions:
+
+```javascript
+lightdm.authenticate(username)
+
+lightdm.respond(response)
+
+lightdm.start_session(session)
+```
+
+### [lightdm.authenticate(username)](/api/Greeter.md#LightDM.Greeter+authenticate)
+This method starts the authentication procedure for a user, allowing to start the user session.
+
+### lightdm.respond(response)
+Provide a response to a prompt. Basically, this acts like a password provider. After the authentication is initiated, you need to provide the user password with this method. It could be "12345", "password", "strongpassword", y'know, a password.
+
+> NOTE: If authentication is not initiated, this will cause an error.
+
+### lightdm.start_session(session)
+Starts a session for the authenticated user. After the user is authenticated, you will need to start the session with this method.
+
+> NOTE: If user is not authenticated, this won't work.
+
+And that's it. You can create a simple javascript file with this:
+```javascript
+lightdm.authenticate("superuser")
+lightdm.respond("superpassword")
+lightdm.start_session("ubuntu")
+```
+
+Although, if this could really work, it won't at first. The `lightdm` object is not available when the greeter is initiated, it is after a little delay. To make this work, an event is triggered when the API is ready to be used. Add an event listener to the `GreeterReady` event.
+
+```javascript
+window.addEventListener("GreeterReady", initGreeter)
+```
+
+And so, it will look like this:
+
+```javascript
+function initGreeter() {
+  lightdm.authenticate("superuser")
+  lightdm.respond("superpassword")
+  lightdm.start_session("ubuntu")
+}
+
+window.addEventListener("GreeterReady", initGreeter)
+```

docs/index.js

@@ -3,7 +3,7 @@ const jsdoc2md = require("jsdoc-to-markdown")
 const fs = require('fs')
 const path = require('path')
 
-const outputDir = "./docs/"
+const outputDir = "./docs/api/"
 
 function generateFiles(file) {
   const templateData = jsdoc2md.getTemplateDataSync({
@@ -11,16 +11,22 @@ function generateFiles(file) {
     //configure: "./jsdoc.json"
   })
 
-  let classNames = templateData.reduce( (classNames, identifier) => {
+  let selectedData = templateData.reduce( (selectedData, identifier) => {
-    if (identifier.kind == 'class') {
+    if (identifier.kind == 'class' || identifier.kind == 'namespace') {
-      classNames.push(identifier.name)
+      selectedData.push(identifier)
     }
-    return classNames
+    return selectedData
   }, [])
 
-  for (const className of classNames) {
+  for (const identifier of selectedData) {
-    const template = `{{#class name="${className}"}}{{>docs}}{{/class}}`
+    let template = ""
-    console.log(`rendering ${className}, template: ${template}`)
+    let name = identifier.name
+    if (identifier.kind == 'class') {
+      template = `{{#class name="${name}"}}{{>docs}}{{/class}}`
+    } else {
+      template = `{{#namespace name="${name}"}}{{>header~}}{{>body}}{{/namespace}}`
+    }
+    console.log(`rendering ${name}, template: ${template}`)
 
     const output = jsdoc2md.renderSync({
       data: templateData,
@@ -30,7 +36,7 @@ function generateFiles(file) {
       "module-index-format": "none"
     })
 
-    fs.writeFileSync(path.resolve(outputDir, `${className}.md`), output)
+    fs.writeFileSync(path.resolve(outputDir, `${name}.md`), output)
   }
 }
 

docs/package.json

@@ -7,13 +7,16 @@
     "src": "src"
   },
   "scripts": {
-    "build": "node index.js",
+    "docs": "node index.js",
-    "clean": "rm docs/* -f"
+    "clean": "rm docs/api/* -f",
+    "build": "honkit build",
+    "serve": "honkit serve"
   },
   "keywords": [],
   "author": "",
   "license": "ISC",
   "devDependencies": {
+    "honkit": "^3.6.20",
     "jsdoc-to-markdown": "^7.0.1"
   }
 }

docs/src/Greeter.js

@@ -30,7 +30,7 @@
  * Base class for the greeter's Theme JavaScript API. Greeter themes will interact
  * directly with an object derived from this class to facilitate the user log-in process.
  * The greeter will automatically create an instance when it starts.
- * The instance can be accessed using the global variable: [`lightdm`](#dl-window-lightdm).
+ * The instance can be accessed using the global variable: `lightdm`.
  *
  * @memberOf LightDM
  */
@@ -84,14 +84,10 @@ class Greeter {
 	get batteryData() {}
 
 	/**
-	 * Gets the brightness
+	 * The display brightness
 	 * @type {Number}
 	 */
 	get brightness() {}
-	/**
-	 * Sets the brightness
-	 * @param {Number} quantity The quantity to set
-	 */
 	set brightness( quantity ) {}
 
 	/**
@@ -395,14 +391,6 @@ class Greeter {
 
 }
 
-class Signal {
-
-	connect( callback ) {}
-
-	disconnect( callback ) {}
-}
-
-
 /**
  * Moment.js instance - Loaded and instantiated automatically by the greeter.
  * @name moment

docs/src/GreeterConfig.js

@@ -30,7 +30,7 @@
  * Provides greeter themes with a way to access values from the greeter's config
  * file located at `/etc/lightdm/web-greeter.yml`. The greeter will
  * create an instance of this class when it starts. The instance can be accessed
- * with the global variable: [`greeter_config`](#dl-window-greeter_config).
+ * with the global variable: `greeter_config`.
  *
  * @memberOf LightDM
  */
@@ -73,14 +73,10 @@ class GreeterConfig  {
 	 * @type {Object}
 	 * @property {Boolean} battery				 Enable greeter and themes to ger battery status.
 	 * @property {Object}  backlight
-	 * @property {Boolean} enabled				 Enable greeter and themes to control display backlight.
+	 * @property {Boolean} backlight.enabled				 Enable greeter and themes to control display backlight.
-	 * @property {Number}  value					 The amount to increase/decrease brightness by greeter.
+	 * @property {Number}  backlight.value					 The amount to increase/decrease brightness by greeter.
-	 * @property {Number}  steps					 How many steps are needed to do the change.
+	 * @property {Number}  backlight.steps					 How many steps are needed to do the change.
 	 */
 	get features() {}
 }
 
-
-
-
-

docs/src/LightDMObjects.js

@@ -35,6 +35,7 @@
 
 /**
  * The greeter's Theme JavaScript API.
+ * Accesible through `lightdm` global variable.
  *
  * @namespace LightDM
  */
@@ -42,7 +43,7 @@
 
 /**
  * Interface for object that holds info about a session. Session objects are not
- * created by the theme's code, but rather by the [`LightDM.Greeter`](#dl-LightDM-Greeter) class.
+ * created by the theme's code, but rather by the [`LightDM.Greeter`](Greeter.md) class.
  *
  * @memberOf LightDM
  */
@@ -84,7 +85,7 @@ class Session  {
 
 /**
  * Interface for object that holds info about a language on the system. Language objects are not
- * created by the theme's code, but rather by the [`LightDM.Greeter`](#dl-LightDM-Greeter) class.
+ * created by the theme's code, but rather by the [`LightDM.Greeter`](Greeter.md) class.
  *
  * @memberOf LightDM
  */
@@ -126,7 +127,7 @@ class Language {
 
 /**
  * Interface for object that holds info about a keyboard layout on the system. Language
- * objects are not created by the theme's code, but rather by the [`LightDM.Greeter`](#dl-LightDM-Greeter) class.
+ * objects are not created by the theme's code, but rather by the [`LightDM.Greeter`](Greeter.md) class.
  *
  * @memberOf LightDM
  */
@@ -168,7 +169,7 @@ class Layout {
 
 /**
  * Interface for object that holds info about a user account on the system. User
- * objects are not created by the theme's code, but rather by the [`LightDM.Greeter`](#dl-LightDM-Greeter) class.
+ * objects are not created by the theme's code, but rather by the [`LightDM.Greeter`](Greeter.md) class.
  *
  * @memberOf LightDM
  */
@@ -253,7 +254,7 @@ class User {
 }
 
 /**
- * Interface for object that holds info about the battery on the system. This object is not created by the theme's code, but rather by the [`LightDM.Greeter`](#dl-LightDM-Greeter) class.
+ * Interface for object that holds info about the battery on the system. This object is not created by the theme's code, but rather by the [`LightDM.Greeter`]{@link Greeter.md} class.
  *
  * @memberOf LightDM
  */
@@ -291,3 +292,25 @@ class Battery {
 		return this._state;
 	}
 }
+
+
+/**
+ * Interface for signals connected to LightDM itself. This is not created by the theme's code, but rather by Web Greeter.
+ * When Web Greeter triggers the signal, all calbacks are executed.
+ *
+ * @memberOf LightDM
+ */
+class Signal {
+
+	/**
+	 * Connects a callback to the signal.
+	 * @param {Function} callback The callback to attach.
+	 */
+	connect( callback ) {}
+
+	/**
+	 * Disconnects a callback to the signal.
+	 * @param {Function} callback The callback to disattach.
+	 */
+	disconnect( callback ) {}
+}

docs/src/ThemeUtils.js

@@ -35,7 +35,7 @@ let localized_invalid_date = null,
 /**
  * Provides various utility methods for use in greeter themes. The greeter will automatically
  * create an instance of this class when it starts. The instance can be accessed
- * with the global variable: [`theme_utils`](#dl-window-theme_utils).
+ * with the global variable: `theme_utils`.
  *
  * @memberOf LightDM
  */