Merge pull request #520 from jpmorganchase/working-docs

Fixed `docs` task

.gitignore

@@ -95,7 +95,7 @@ node_modules
 *.mem
 ftpsync.settings
 *.log
-*.png
+screenshots/
 Gemfile
 Gemfile.lock
 Vagrantfile
@@ -135,3 +135,4 @@ docs/perspective.*.rst
 docs/python
 package.json.bak
 yarn.lock.bak
+docs/static/img

README.md

@@ -49,5 +49,5 @@ simple to build real-time & user configurable analytics entirely in the browser.
 * [Installation](https://jpmorganchase.github.io/perspective/docs/installation.html)
 * [User's Guide](https://jpmorganchase.github.io/perspective/docs/usage.html)
 * [Developer's Guide](https://jpmorganchase.github.io/perspective/docs/development.html)
-* [Perspective API](https://jpmorganchase.github.io/perspective/docs/perspective.html)
-* [Perspective Viewer API](https://jpmorganchase.github.io/perspective/docs/perspective-viewer.html)
+* [Perspective API](https://github.com/jpmorganchase/perspective/blob/master/packages/perspective/README.md)
+* [Perspective Viewer API](https://github.com/jpmorganchase/perspective/blob/master/packages/perspective-viewer/README.md)

cpp/perspective/CMakeLists.txt

@@ -447,16 +447,25 @@ if(PSP_BUILD_DOCS)
 	add_custom_target(doxygen)
 	add_custom_command(TARGET doxygen
 	    COMMAND doxygen doxygen.conf
-	    WORKING_DIRECTORY ../docs
+	    WORKING_DIRECTORY ../../docs
 	    COMMENT "Build doxygen xml files used by sphinx/breathe."
 	)
 
-    add_custom_target(docs-html ALL)
-    add_custom_command(TARGET docs-html
-	    COMMAND sphinx-build -b html . _build/html
-        WORKING_DIRECTORY ../docs
-        COMMENT "Build html documentation"
-    	)
-   	add_dependencies(docs-html doxygen)
+	add_custom_target(docs-html ALL)
+	add_custom_command(TARGET docs-html
+		COMMAND sphinx-build -b html . build/html
+			WORKING_DIRECTORY ../../docs
+			COMMENT "Build html documentation"
+		)
+	add_dependencies(docs-html doxygen)
+
+	# add_custom_target(docs-markdown ALL)
+	# add_custom_command(TARGET docs-html
+	# 	COMMAND sphinx-build -M markdown . build/
+	# 		WORKING_DIRECTORY ../../docs
+	# 		COMMENT "Build markdown documentation"
+	# 	)
+	# add_dependencies(docs-html doxygen)
+
 endif()
 ##########

docker/docs/Dockerfile

@@ -27,10 +27,9 @@ RUN ln -s /usr/local/lib/libboost_numpy37.so /usr/local/lib/libboost_numpy.so
 RUN python3 -m pip install 'numpy>=1.13.1' 'pandas>=0.22.0'
 
 # docs dependencies
-RUN python3 -m pip install breathe sphinx sphinx_rtd_theme
-RUN npm install @babel/cli @babel/core @babel/plugin-proposal-decorators @babel/plugin-transform-for-of  @babel/preset-env babel-plugin-transform-custom-element-classes jsdoc jsdoc-babel --save-dev
-RUN yarn
+RUN python3 -m pip install breathe sphinx_rtd_theme sphinx
 
 # install from here from now, waiting on https://github.com/mozilla/sphinx-js/issues/94
 RUN python3 -m pip install git+https://github.com/timkpaine/sphinx-js
+RUN python3 -m pip install git+https://github.com/texodus/recommonmark
 

docs/README.md

@@ -0,0 +1,11 @@
+# Perspective Documentation Site
+
+This is the source for the [Perspective documentaiton github-pages site](https://jpmorganchase.github.io/perspective/) - 
+what you're looking for is probably there.  Links to the source documenation
+from which the site is rendered:
+
+* [Installation](https://github.com/jpmorganchase/perspective/blob/master/docs/md/installation.html)
+* [User's Guide](https://github.com/jpmorganchase/perspective/blob/master/docs/md/usage.html)
+* [Developer's Guide](https://github.com/jpmorganchase/perspective/blob/master/docs/md/development.html)
+* [Perspective API](https://github.com/jpmorganchase/perspective/blob/master/packages/perspective/README.md)
+* [Perspective Viewer API](https://github.com/jpmorganchase/perspective/blob/master/packages/perspective-viewer/README.md)

docs/blog/2018-10-01-v0.2.0-release.md

@@ -0,0 +1,124 @@
+---
+title: 0.2.0 Release
+author: Andrew Stein
+authorURL: http://github.com/texodus
+authorImageURL: https://avatars3.githubusercontent.com/u/60666?s=400&v=4
+---
+
+After nine months of tireless development and over 700 commits from 18 
+exceptionally talented [contributors](https://github.com/jpmorganchase/perspective/graphs/contributors),
+we are pleased to announce the v0.2.0 release of Perspective!  With this release
+comes a cavalcade of exciting features, performance optimizations, bug fixes, 
+and <strike>easter eggs</strike> usability improvements.
+
+Get started quickly with our [new and improved documentation](https://jpmorganchase.github.io/perspective/docs/installation.html),
+or try out some [live examples on JSFiddle](https://jsfiddle.net/user/texodus/fiddles/)!
+
+<!--truncate-->
+
+<style>.post img {width:300px;float:left;padding-right: 30px;padding-bottom:20px;display:inline-block}img:</style>
+
+## User Experience
+
+<img src="../../../../img/2018-10-01-v0.2.0-release/jupyter.png"></img>
+
+Perspective now features a first class & completely symmetric 
+[JupyterLab](https://jupyterlab.readthedocs.io/en/latest/) widget, via the
+[perspective-python](https://github.com/timkpaine/perspective-python)
+package, available via pip.
+
+
+<br style="clear:both;" />
+<img src="../../../../img/2018-10-01-v0.2.0-release/theme.png"></img>
+
+The new [Material](https://material.io/design/) inspired design is clear, functional and 
+trendy.  Comes in both [Day](https://unpkg.com/@jpmorganchase/perspective-examples@0.2.0/build/theme-material.html), 
+and a [Night](https://unpkg.com/@jpmorganchase/perspective-examples@0.2.0/build/theme-material-dark.html) 
+flavor for after market hours (be sure to [wear sunglasses!](../../../../img/2018-10-01-v0.2.0-release/sunglasses.png)).
+
+<br style="clear:both;" />
+<img src="../../../../img/2018-10-01-v0.2.0-release/interface.png"></img>
+
+Perspective's User Interface has seen readability, usability and functionality 
+changes, including better control labels, column remove buttons, sort direction
+indicators, filter operator `select`, auto-complete of filter terms based on data,
+smart parsing filter dates;  just to name a few!
+
+<br style="clear:both;" />
+<img src="../../../../img/2018-10-01-v0.2.0-release/computed.png"></img>
+
+Computed Columns allow you to create time-bucketed series, categorize and group
+values by function, combine columns through simple mathematical operations, 
+duplicate columns for calculating multiple aggregates, and
+much, much more!
+
+<br style="clear:both;" />
+<img src="../../../../img/2018-10-01-v0.2.0-release/remote.png"></img>
+
+Run Perspective without your data ever leaving the server!  With Perspective
+running in Remote mode, the entire User Experience can be virtualized to the
+server, rather than downloading your data to the client, substantially improving
+performance for enormous datasets.  All in just a few lines of code!
+
+<br style="clear:both;" />
+
+### Highcharts Plugin
+
+<img src="../../../../img/2018-10-01-v0.2.0-release/hierarchial.png"></img>
+
+Hierarchial chart types: `heatmap`, `treemap` and `sunburst`.  See the 
+structure of your pivotted data more clearly than ever before!
+
+<br style="clear:both;" />
+<img src="../../../../img/2018-10-01-v0.2.0-release/subchart.png"></img>
+
+Sub-charts are rendered for `column-pivot` categories on `treemap` and
+`sunburst` chart types, allowing you to separately chart any data category.
+
+<br style="clear:both;" />
+<img src="../../../../img/2018-10-01-v0.2.0-release/boost.png"></img>
+
+Substantial performance improvements for most chart types, which will
+now also take advantage of [Highcharts boost mode]() where available, allow
+visualization of substantially larger datasets.
+
+<br style="clear:both;" />
+<img src="../../../../img/2018-10-01-v0.2.0-release/axis.png"></img>
+
+Category (string) and Date/time Axis types are available on all charts, where
+they will be applied automatically based on your data's <i>schema</i>.
+
+<br style="clear:both;" />
+
+### Hypergrid Plugin
+
+In addition to a new <i>lazy mode</i> which only loads data visible in the
+viewport, substantially improving render performance for huge datasets,
+Perspective's Hypergrid plugin received one of the most requested features
+ever:
+
+<img src="../../../../img/2018-10-01-v0.2.0-release/expandcollapse.png"></img>
+
+By popular demand, collapse rows alone or in groups, and even 
+[across real-time updates](https://unpkg.com/@jpmorganchase/perspective-examples@0.2.0/build/streaming.html).
+
+<br style="clear:both;" />
+
+* (major) Bug fixes
+    * Better input type inference, better automated output formatting (dates).
+    * Better support for Apache Arrow, for the ultimate in load-time performance.
+    * More consistent use of `promise` for asynchronous APIs.
+
+* New APIs
+    * Clipboard, config save/restore, export, reset, row delete `<perspective-viewer>` APIs.
+    * `to_columns()`, `to_csv()` output methods.
+    * Partial updates and <i>unset</i> cell semantics.
+    * `weighted_mean` aggregate, 'in' filter operator.
+    * `WorkerHost()` for powering `<perspective-viewer>` via a remote Node.js process.
+    * Lifecycle events.
+
+* Structural improvements
+    * Deprecation of the `perspective-common` and `perspective-examples` modules.
+    * A new top-level `examples/` directory containing full example projects.
+    * Flattened Web Assembly asset strucutre for a smaller module, simpler 
+      project integration and easier hosting.