Merge pull request #11 from thclark/v0.0.1

v0.0.1

Author: thclark

.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+exclude: 'build|docs|node_modules|.git|.tox|dist'
+default_stages: [commit]
+fail_fast: true
+default_language_version:
+  python: python3  # force all unspecified python hooks to run python3
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: master
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+        language_version: python3
+
+  - repo: https://github.com/thclark/pre-commit-sphinx
+    rev: 0.0.1
+    hooks:
+      - id: build-docs
+        language_version: python3

CMakeSettings.json

@@ -27,7 +27,7 @@
         "cmakeCommandArgs": "-T host=x64",
         "buildCommandArgs": "-m -v:minimal",
         "ctestCommandArgs": ""
-        
+
       },
       {
         "name": "x64-Release",
@@ -39,4 +39,4 @@
         "ctestCommandArgs": ""
       }
     ]
-}
+}

README.md

@@ -1,104 +1,50 @@
-# cpplot
-
-> **Work is in progress to refactor this out from other libraries. Watch this space.**
-
-Interactive graphs and charts for C++ 11 upward,
-[interactively viewable in-browser using cpplot-viewer](https://cpplot.herokuapp.com).
-
-This library allows you to save figure files (in a *.json form compliant with the `plotly.js` library) to disk
-during program execution.
-
-
-## Why?
-
-For most engineering and scientific applications that come across my desk, it's a case of "prototype in MATLAB or Python, rewrite in C++". But:
- - I'm getting really sick of MATLAB in terms of deployability (there's no CI option to build it, the slug size of the runtime library is 3.7Gb, etc etc).
- - I'm getting really really sick of writing the damn code twice.
- - Most of my engineering and science apps are now getting deployed to cloud services. So displaying natively generated figures in-browser is a nightmare.
-
-What I need is a solution where I can prototype straight into a language which is fast, capable and has a pretty good ecosystem of third party libraries to help me.
-
-Now, with:
- - the great improvements to C++ in the C++11 and 14 standards (which make it much easier to handle threading and generally connect APIs of various libraries together),
- - availability of libraries like Eigen, cpr, ceres-solver, Intel MKL, cxxopts (I could go on and on),
- - great utilities like googletest and Cmake to remove all the old-skool build and test agony...
-
-C++ is really getting there. The one thing missing is a plotting library, which allows me to:
- - quickly and easily prototype new algorithms (visually diagnose what's wrong etc etc)
- - display analysis results on the web
- - produce the same figures on different platforms
- - save publication quality figures easily
-
-In all the other languages I use, I now use `plotly` to do those things. So now it's here for C++ too.
-
-
-## Viewing Figures
-
-A browser based utility is supplied at [https://cpplot.herokuapp.com](https://cpplot.herokuapp.com).
-Navigate to that link and you'll easily be able to view and export the figures created here.
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+[![black-girls-code](https://img.shields.io/badge/black%20girls-code-f64279.svg)](https://www.blackgirlscode.com/)
 
-The browser viewer is built in React (using the excellent `react-plotly.js`), is also open-source, free and it
-always keeps your data local (files are never uploaded to a server). Find the source
-at [https://github.com/thclark/cpplot-viewer](https://github.com/thclark/cpplot-viewer).
 
-**Some example figures to try out with the viewer are included in `/examples`**.
-
-## The Plotly Library
-
-### Plotly figure json specs
-
-At the core of plotly is a set of open specifications for JSON data which can be rendered into various figure types. The various figure classes available here
-
-### Plotly Offline
+# cpplot
 
-`Plotly.js` is a javascript library for rendering figures, which can be used offline. This is what's used by the browser viewer.
+Interactive graphs and charts for C++ 11 upward,
+[viewable in-browser using cpplot-viewer](https://cpplot.herokuapp.com).
 
-### Plotly Online
+Full documentation is at [https://cpplot.readthedocs.io](https://cpplot.readthedocs.io)
 
-Plotly have a range of online services for collaboration on data grids and figures. You can use their API or tools to take the contents of the files produced here (plotly compliant JSON strings) onto Plotly Online, but how to do that is out of scope here (check their docs).
 
-**HELP WANTED** - I have a branch that's starting to use the Plotly API, which might be the very early beginning of a
-client SDK for C++, enabling direct manipulation of online data. However, I have very little appetite for this (I personally don't use plotly online) so collaborators are welcome.
 
 
 ## For Developers
 
+You should only need to read the following if you plan to develop on `cpplot`.
+
 ### Style guide
 
 We use the [Google C++ style guide](https://google.github.io/styleguide/cppguide.html) with the following exceptions:
  - Don't care about line width so long as its within reason
  - Use 4 space indenting, not 2 as suggested by the style guide, because we're not [total monsters](https://www.youtube.com/watch?v=SsoOG6ZeyUI) (just kidding xx).
 
-### Threading
-
-Figure write-to-disk is called as an async task, so doesn't block the main computation thread.
+### Pre-Commit
 
-This delays program termination when the main program executes quicker than the figure write.
-TODO consider creating daemonised threads for writing figures.
-
-### Third party dependencies
-
-We are currently using:
-
-[**Eigen**](http://eigen.tuxfamily.org/) provides a linear algebra library. It isn't as consistent with MATLAB's API as armadillo (an alternative), but the API is very understandable and is used extensively in the C++ community.
+You need to install pre-commit to get the hooks working. Do:
+```
+pip install pre-commit
+pre-commit install
+```
 
-[**glog**](https://github.com/google/glog) google's asynchronous logging library, used for logging to file.
+Once that's done, each time you make a commit, the following checks are made:
 
-[**googletest**](https://github.com/google/googletest) for unit testing.
+- valid github repo and files
+- code style
+- documentation builds correctly
 
-### Submodule dependencies
+Upon failure, the commit will halt. **Re-running the commit will automatically fix most issues** except:
+- You'll have to fix documentation yourself prior to a successful commit (there's no auto fix for that!!).
 
-You'll need to clone the repository **and its submodules, cpr and json,** in order to build it.
+You can run pre-commit hooks without making a commit, like:
 ```
-git clone --recurse-submodules https://github.com/thclark/cpplot
+pre-commit run build-docs
 ```
+which is useful to locally build documents without crazy efforts setting up an environment for sphinx.
 
-### Third party library installation (OSX)
-
-**ceres-solver which includes eigen and glog dependencies:**
-```bash
-brew install homebrew/science/ceres-solver
-```
 
 ### Compilation with cmake
 

docs/.gitignore

@@ -0,0 +1,4 @@
+doctrees
+html
+source/doxyoutput*
+source/library_api*

docs/requirements.txt

@@ -0,0 +1,8 @@
+
+# Required by the python script for building documentation. You probably won't have to install this (because you can
+# pre-commit hook builds docs for you and manages the environment).
+Sphinx==1.8.3
+sphinx-rtd-theme==0.4.2
+sphinx-tabs==1.1.10
+breathe==4.11.1
+exhale==0.2.1

docs/source/about.rst

@@ -0,0 +1,80 @@
+.. _about:
+
+=====
+About
+=====
+
+.. _why:
+
+Why?
+====
+
+For most engineering and scientific applications that come across my
+desk, it's a case of "prototype in MATLAB or Python, rewrite in C++".
+But: - I'm getting really sick of MATLAB in terms of deployability
+(there's no CI option to build it, the slug size of the runtime library
+is 3.7Gb, etc etc). - I'm getting really really sick of writing the damn
+code twice. - Most of my engineering and science apps are now getting
+deployed to cloud services. So displaying natively generated figures
+in-browser is a nightmare.
+
+What I need is a solution where I can prototype straight into a language
+which is fast, capable and has a pretty good ecosystem of third party
+libraries to help me.
+
+Now, with: - the great improvements to C++ in the C++11 and 14 standards
+(which make it much easier to handle threading and generally connect
+APIs of various libraries together), - availability of libraries like
+Eigen, cpr, ceres-solver, Intel MKL, cxxopts (I could go on and on), -
+great utilities like googletest and Cmake to remove all the old-skool
+build and test agony...
+
+C++ is really getting there. The one thing missing is a plotting
+library, which allows me to: - quickly and easily prototype new
+algorithms (visually diagnose what's wrong etc etc) - display analysis
+results on the web - produce the same figures on different platforms -
+save publication quality figures easily
+
+In all the other languages I use, I now use ``plotly`` to do those
+things. So now it's here for C++ too.
+
+
+.. _about_plotly:
+
+About Plotly
+============
+
+**cpplot** is based on the plot.ly json schema for figures and charts.
+
+Plotly figure json schema
+-------------------------
+
+At the core of plotly is a set of open specifications for JSON data
+which can be rendered into various figure types. The plotly team
+have hung a lot of services and offerings around it,
+but basically everything boils down to a `json schema <https://plotly.com/chart-studio-help/json-chart-schema/>__`.
+
+**cpplot** helps generate JSON which is compliant with that schema.
+
+Plotly Offline
+--------------
+
+``Plotly.js`` is an excellent javascript library for rendering figures, which can
+be used offline or in any third party app. This is what's used by the browser viewer.
+
+Plotly Online
+-------------
+
+Plot.ly have a range of online services, and anything produced by **cpplot** will be
+importable there, since it's compliant with their schema.
+
+I'm not a marketing person for plotly, so how to do that is out of scope here (check their docs)!!
+
+I have a branch that has some code using the Plotly API,
+which might be the very early beginning of a client SDK for C++,
+enabling direct manipulation of online data. However, I have very little
+appetite for this (I personally don't use plotly online, because I've
+found the support to be appalling in the past) but collaborators
+committed to developing and maintaining that would be welcome. File an issue if you're interested.
+
+