Fix #1475 documentation with docma (#1539)

Fix #1475. Add documentation using docma: gets markdown from docs dir gets jsdoc from reducers, actions, epics, components and plugins create a single page application to deploy inside mapstore2 directly Fixes #1300 documenting some plugins, together with actions, reducers, epics
geosolutions-it · Mar 13, 2017 · fa7095c · fa7095c
1 parent c735782
commit fa7095c
Show file tree

Hide file tree

Showing 15 changed files with 563 additions and 31 deletions.
diff --git a/build.sh b/build.sh
@@ -4,5 +4,7 @@ set -e
 npm install
 npm run compile
 npm run lint
+npm run doc
 npm test
 mvn clean install
+npm run cleandoc
diff --git a/docma-config.json b/docma-config.json
@@ -0,0 +1,131 @@
+{
+    "debug": 1,
+    "jsdoc": {
+        "encoding": "utf8",
+        "recurse": false,
+        "pedantic": false,
+        "access": null,
+        "package": null,
+        "module": true,
+        "undocumented": false,
+        "undescribed": false,
+        "hierarchy": true,
+        "sort": "alphabetic",
+        "relativePath": null,
+        "filter": null,
+        "allowUnknownTags": true,
+        "plugins": ["plugins/markdown"]
+    },
+    "markdown": {
+        "gfm": true,
+        "tables": true,
+        "breaks": false,
+        "pedantic": false,
+        "sanitize": false,
+        "smartLists": true,
+        "smartypants": false,
+        "tasks": true,
+        "emoji": true
+    },
+    "app": {
+        "title": "MapStore 2 documentation",
+        "base": "/mapstore/docs",
+        "entrance": "content:readme",
+        "routing": { "method": "path", "caseSensitive": true }
+    },
+    "template": {
+        "path": "default",
+        "options": {
+            "title": "MapStore 2",
+            "sidebar": true,
+            "collapsed": false,
+            "outline": "tree",
+            "badges": true,
+            "search": true,
+            "navbar": true,
+            "navItems": [
+                {
+                    "iconClass": "ico-book",
+                    "label": "Guides",
+                    "items": [
+                        { "label": "Home", "href": "./" },
+                        { "separator": true },
+                        { "label": "Developer's guide", "href": "developer-guide" },
+                        { "separator": true },
+                        { "label": "Plugins Architecture", "href": "plugins-architecture" },
+                        { "label": "Configuring Plugins", "href": "plugins-documentation" },
+                        { "separator": true },
+                        { "label": "Project Creation Script", "href": "project-creation-script" }
+                    ]
+                },
+                {
+                    "iconClass": "ico-mouse-pointer",
+                    "label": "Reference",
+                    "items": [
+                        { "label": "Components", "href": "api/components"},
+                        { "label": "Actions", "href": "api/actions" },
+                        { "label": "Reducers", "href": "api/reducers" },
+                        { "label": "Epics", "href": "api/epics" },
+                        { "separator": true },
+                        { "label": "Plugins", "href": "api/plugins" }
+
+                    ]
+                },
+                {
+                    "iconClass": "ico-md ico-download",
+                    "label": "Download",
+                    "href": "index.html",
+                    "items": [
+                        { "label": "<code>mvn clean install</code>" },
+                        {
+                            "label": "MapStore 2 Releases",
+                            "href": "https://github.com/geosolutions-it/MapStore2/releases",
+                            "target": "_blank"
+                        },
+                        {
+                            "label": "MapStore 2 tar.gz",
+                            "href": "https://github.com/geosolutions-it/MapStore2/tarball/master",
+                            "target": "_blank"
+                        },
+                        {
+                            "label": "MapStore 2 .zip",
+                            "href": "https://github.com/geosolutions-it/MapStore2/zipball/master",
+                            "target": "_blank"
+                        }
+
+                    ]
+                },
+                {
+                    "iconClass": "ico-md ico-github",
+                    "label": "GitHub",
+                    "href": "https://github.com/geosolutions-it/MapStore2",
+                    "target": "_blank"
+                }
+            ]
+        }
+    },
+    "src": [
+        {
+          "components" : ["web/client/components/mapcontrols/search/SearchBar.jsx"],
+           "actions" : ["web/client/actions/search.js"],
+           "reducers" : ["web/client/reducers/search.js"],
+            "epics": "web/client/epics/search.js",
+            "plugins": [
+                "web/client/plugins/Search.jsx",
+                "web/client/plugins/BackgroundSwitcher.jsx",
+                "web/client/plugins/Map.jsx",
+                "web/client/plugins/Identify.jsx"
+            ]
+        },
+        "./docs/**/*md",
+        {
+            "readme": "./README.md",
+            "site": "./docs/index.md",
+            "developer-guide": "./docs/developer-guide/index.md",
+            "plugins-architecture": "./docs/developer-guide/plugins-architecture.md",
+            "building-and-developing": "./docs/developer-guide/plugins-architecture.md",
+            "plugins-documentation": "./docs/developer-guide/plugins-documentation.md",
+            "project-creation-script": "./docs/developer-guide/project-creation-script.md"
+        }
+    ]
+}
diff --git a/package.json b/package.json
@@ -16,6 +16,7 @@
     "babel-preset-react": "6.5.0",
     "babel-preset-stage-0": "6.5.0",
     "css-loader": "0.19.0",
+    "docma": "1.5.1",
     "download-cli": "1.0.1",
     "escope": "3.2.0",
     "eslint": "0.24.1",
@@ -26,6 +27,8 @@
     "file-loader": "0.8.5",
     "html-webpack-plugin": "2.17.0",
     "istanbul-instrumenter-loader": "2.0.0",
+    "jsdoc": "^3.4.3",
+    "jsdoc-jsx": "^0.1.0",
     "karma": "1.5.0",
     "karma-chrome-launcher": "2.0.0",
     "karma-cli": "1.0.1",
@@ -151,14 +154,17 @@
     "xml2js": "0.4.17"
   },
   "scripts": {
+    "doc": "docma -c docma-config.json --dest web/docs",
+    "cleandoc": "rimraf web/docs && rimraf web/client/mapstore/docs",
+    "doctest": "docma -c docma-config.json --dest web/client/mapstore/docs && echo documentation is accessible from the mapstore/docs path when running start sript",
     "postinstall": "node checkCesium.js && mkdirp ./web/client/libs/Cesium && download --extract --out ./web/client/libs/Cesium https://cesiumjs.org/releases/Cesium-1.17.zip || echo Cesium already installed",
     "clean": "rimraf ./web/client/dist",
     "compile": "npm run clean && mkdirp ./web/client/dist && webpack --progress --config prod-webpack.config.js",
     "analyze": "npm run clean && mkdirp ./web/client/dist && webpack --json | webpack-bundle-size-analyzer",
     "start": "webpack-dev-server --progress --colors --port 8081 --hot --inline --content-base web/client",
     "examples": "webpack-dev-server --progress --colors --port 8081 --hot --inline --content-base web/client --config examples-webpack.config.js",
     "test": "karma start ./karma.conf.single-run.js",
-    "pretest": "npm run lint",
+    "pretest": "npm run cleandoc && npm run lint",
     "continuoustest": "karma start ./karma.conf.continuous-test.js",
     "mvntest": "karma start ./karma.conf.single-run.js --reporters junit,dots,coverage",
     "lint": "eslint web/client --ext .jsx,.js",

diff --git a/web/client/actions/search.js b/web/client/actions/search.js
@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright 2015, GeoSolutions Sas.
  * All rights reserved.
  *
@@ -18,7 +18,13 @@ const TEXT_SEARCH_NESTED_SERVICES_SELECTED = 'TEXT_SEARCH_NESTED_SERVICE_SELECTE
 const TEXT_SEARCH_ERROR = 'TEXT_SEARCH_ERROR';
 const TEXT_SEARCH_CANCEL_ITEM = 'TEXT_SEARCH_CANCEL_ITEM';
 const TEXT_SEARCH_ITEM_SELECTED = 'TEXT_SEARCH_ITEM_SELECTED';
-
+/**
+ * updates the results of the search result loaded
+ * @memberof actions.search
+ * @param {geojsonFeature[]} results array of search results
+ * @param {boolean} append [false] tells to append the result to existing ones or not
+ * @param {object[]} servies services intrested to use for the next search
+ */
 function searchResultLoaded(results, append=false, services) {
     return {
         type: TEXT_SEARCH_RESULTS_LOADED,
@@ -27,47 +33,79 @@ function searchResultLoaded(results, append=false, services) {
         services
     };
 }
-
+/**
+ * updates the search text
+ * @memberof actions.search
+ * @param {string} text the new text
+ */
 function searchTextChanged(text) {
     return {
         type: TEXT_SEARCH_TEXT_CHANGE,
         searchText: text
     };
 }
-
+/**
+ * trigger search text loading
+ * @memberof actions.search
+ * @param {boolean} loading boolean flag
+ */
 function searchTextLoading(loading) {
     return {
         type: TEXT_SEARCH_LOADING,
         loading
     };
 }
+
+/**
+ * an error occurred during text searchText
+ * @memberof actions.search
+ * @param error the error
+ */
 function searchResultError(error) {
     return {
         type: TEXT_SEARCH_ERROR,
         error
     };
 }
 
-
+/**
+ * clear the results
+ * @memberof actions.search
+ */
 function resultsPurge() {
     return {
         type: TEXT_SEARCH_RESULTS_PURGE
     };
 }
 
+/**
+ * reset the search text and clear results
+ * @memberof actions.search
+ */
 function resetSearch() {
     return {
         type: TEXT_SEARCH_RESET
     };
 }
 
+/**
+ * add a marker to the search result layer
+ * @memberof actions.search
+ * @param {object} itemPosition
+ */
 function addMarker(itemPosition) {
     return {
         type: TEXT_SEARCH_ADD_MARKER,
         markerPosition: itemPosition
     };
 }
 
+/**
+ * perform a text search
+ * @memberof actions.search
+ * @param {string} searchText the text to search
+ * @param {object} options [{}] the search options. Contain the services
+ */
 function textSearch(searchText, {services = null} = {}) {
     return {
         type: TEXT_SEARCH_STARTED,
@@ -76,6 +114,12 @@ function textSearch(searchText, {services = null} = {}) {
     };
 }
 
+/**
+ * Trigger when an item is selected from the search results
+ * @memberof actions.search
+ * @param {object} item the selected item
+ * @param {object} mapConfig the current map configuration (with size, projection...)
+ */
 function selectSearchItem(item, mapConfig) {
     return {
         type: TEXT_SEARCH_ITEM_SELECTED,
@@ -84,6 +128,15 @@ function selectSearchItem(item, mapConfig) {
     };
 
 }
+
+/**
+ * Configures the search tool to perform sub-service queries. It will store the
+ * selected item and configure the new nested services.
+ * @memberof actions.search
+ * @param {object[]} services the of the nested services
+ * @param {object[]} items the selected items
+ * @param {object[]} searchText the new search text
+ */
 function selectNestedService(services, items, searchText) {
     return {
         type: TEXT_SEARCH_NESTED_SERVICES_SELECTED,
@@ -93,6 +146,11 @@ function selectNestedService(services, items, searchText) {
     };
 }
 
+/**
+ * remove an item selected ()
+ * @memberof actions.search
+ * @param {object} item the item to remove
+ */
 function cancelSelectedItem(item) {
     return {
         type: TEXT_SEARCH_CANCEL_ITEM,

diff --git a/web/client/components/mapcontrols/search/SearchBar.jsx b/web/client/components/mapcontrols/search/SearchBar.jsx
@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright 2015, GeoSolutions Sas.
  * All rights reserved.
  *
@@ -24,7 +24,28 @@ var delay = (
 require('./searchbar.css');
 
 /**
- * Search Bar component. With AutoComplete
+ * Search Bar component. With typeAhead events
+ * @memberof components.mapControls.search
+ * @class
+ * @prop {string} className the class to assign to the components
+ * @prop {function} onSearch callback on search event
+ * @prop {function} onPurgeResults triggered when the user clear
+ * @prop {function} onSearchTextChange triggered when the text changes
+ * @prop {function} onCancelSelectedItem triggered when the user deletes the selected item (by hitting backspace) when text is empty
+ * @prop {string} placeholder string to use as placeholder when text is empty
+ * @prop {string} placeholderMsgId msgId for the placeholder. Used if placeholder is not defined
+ * @prop {number} delay milliseconds after trigger onSearch if typeAhead is true
+ * @prop {boolean} hideOnBlur if true, it triggers onPurgeResults on blur
+ * @prop {boolean} typeAhead if true, onSearch is triggered when users change the search text, after `delay` milliseconds
+ * @prop {number} blurResetDelay time to wait before to trigger onPurgeResults after blur event, if `hideOnBlur` is true
+ * @prop {searchText} the text to display in the component
+ * @prop {object[]} selectedItems the items selected. Must have `text` property to display
+ * @prop {boolean} autoFocusOnSelect if true, the comonent gets focus when items are added, or deleted but some item is still selected. Useful for continue writing after selecting an item (with nested services for instance)
+ * @prop {boolean} loading if true, shows the loading tool
+ * @prop {object} error if not null, an error icon will be display
+ * @prop {object} style css style to apply to the component
+ * @prop {object} options to pass to the search event
+ *
  */
 let SearchBar = React.createClass({
     propTypes: {

diff --git a/web/client/epics/search.js b/web/client/epics/search.js
@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright 2017, GeoSolutions Sas.
  * All rights reserved.
  *
@@ -30,6 +30,15 @@ const toBbox = require('turf-bbox');
 const {generateTemplateString} = require('../utils/TemplateUtils');
 
 const {get} = require('lodash');
+
+/**
+ * Gets every `TEXT_SEARCH_STARTED` event.
+ * Dispatches the request to all the services in the action, postprocess them
+ * and updates every tume the results
+ * @param {Observable} action$ manages `TEXT_SEARCH_STARTED` and `TEXT_SEARCH_RESULTS_PURGE`, `TEXT_SEARCH_RESET`, `TEXT_SEARCH_ITEM_SELECTED` for cancellation
+ * @memberof epics.search
+ * @return {Observable}
+ */
 const searchEpic = action$ =>
   action$.ofType(TEXT_SEARCH_STARTED)
     .debounceTime(250)
@@ -51,6 +60,19 @@ const searchEpic = action$ =>
             .catch(e => Rx.Observable.from([searchResultError(e), searchTextLoading(false)]))
 
 );
+
+/**
+ * Gets every `TEXT_SEARCH_ITEM_SELECTED` event.
+ * on item selections zooms to the selected item, adds the marker to the marker layer and clear
+ * search results.
+ * If the selected item has a `__SERVICE__.then` entry, configures the search tool
+ * to manage the nested services.
+ * If the searvice has a search text template, it configures the searchText with
+ * using the template.
+ * @param {Observable} action$ stream of actions. Manages `TEXT_SEARCH_ITEM_SELECTED`
+ * @memberof epics.search
+ * @return {Observable}
+ */
 const searchItemSelected = action$ =>
     action$.ofType(TEXT_SEARCH_ITEM_SELECTED)
     .mergeMap(action => {