diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 0000000..9a68f71
--- /dev/null
+++ b/.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
diff --git a/CMakeSettings.json b/CMakeSettings.json
index f35e71c..3dea073 100644
--- a/CMakeSettings.json
+++ b/CMakeSettings.json
@@ -27,7 +27,7 @@
"cmakeCommandArgs": "-T host=x64",
"buildCommandArgs": "-m -v:minimal",
"ctestCommandArgs": ""
-
+
},
{
"name": "x64-Release",
@@ -39,4 +39,4 @@
"ctestCommandArgs": ""
}
]
-}
\ No newline at end of file
+}
diff --git a/README.md b/README.md
index 5fa41af..e2413ed 100644
--- a/README.md
+++ b/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.
+[](https://github.com/pre-commit/pre-commit)
+[](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
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..a8a5878
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,4 @@
+doctrees
+html
+source/doxyoutput*
+source/library_api*
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..959002e
--- /dev/null
+++ b/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
diff --git a/docs/source/about.rst b/docs/source/about.rst
new file mode 100644
index 0000000..226f4cb
--- /dev/null
+++ b/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 __`.
+
+**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.
+
+
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 0000000..a952183
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,284 @@
+# -*- coding: utf-8 -*-
+#
+# Documentation build configuration file
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import os
+import sphinx_rtd_theme
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+# sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+# Breathe and exhale are added as recommended by:
+# https://exhale.readthedocs.io/en/latest/usage.html#usage-quickstart-guide
+extensions = [
+ 'sphinx.ext.todo',
+ 'sphinx_tabs.tabs',
+ 'sphinx.ext.mathjax',
+ 'sphinx.ext.ifconfig',
+ 'breathe',
+ 'exhale',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+# source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'cpplot'
+copyright = u'2017-20 Tom Clark'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+
+# The full version, including alpha/beta/rc tags.
+release = os.getenv('RELEASE_TAG', 'x.y.unknown')
+
+# The short X.Y version.
+version = '.'.join(release.split('.')[0:2])
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+# language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+# today = ''
+# Else, today_fmt is used as the format for a strftime call.
+# today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+# default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+# add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+# show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+# modindex_common_prefix = []
+
+# -- Breathe and Exhale Configuration ------------------------------------------
+
+# Setup the breathe extension
+breathe_projects = {
+ "My Project": "./doxyoutput/xml"
+}
+breathe_default_project = "My Project"
+
+# Setup the exhale extension
+# TODO reset the doxygen input to ../../source once conan installation done, this should resent the build correctly
+exhale_args = {
+ # These arguments are required
+ "containmentFolder": "./library_api",
+ "rootFileName": "library_root.rst",
+ "rootFileTitle": "Library API",
+ "doxygenStripFromPath": "../../",
+ # Suggested optional arguments
+ "createTreeView": True,
+ # TIP: if using the sphinx-bootstrap-theme, you need
+ # "treeViewIsBootstrap": True,
+ "exhaleExecutesDoxygen": True,
+ # TODO can't build the api docs while json.hpp is there. Fix once #6 is complete.
+ # "exhaleDoxygenStdin": "INPUT = ../../source ../../source/plot_types"
+ "exhaleDoxygenStdin": "INPUT = ../../source/nowhere"
+}
+
+# Tell sphinx what the primary language being documented is
+primary_domain = 'cpp'
+
+# Tell sphinx what the pygments highlight language should be
+highlight_language = 'cpp'
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+# html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+# html_theme_path = ["_themes",]
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = "cpplot: JSON based figures for C++"
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+html_short_title = "cpplot"
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+# html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+html_favicon = 'favicon.ico'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+# html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+html_domain_indices = True
+
+# If false, no index is generated.
+html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+html_show_sourcelink = False
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+html_show_sphinx = False
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+# html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'libraryDoc'
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+ # The paper size ('letterpaper' or 'a4paper').
+ # 'papersize': 'letterpaper',
+
+ # The font size ('10pt', '11pt' or '12pt').
+ # 'pointsize': '10pt',
+
+ # Additional stuff for the LaTeX preamble.
+ # 'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+ ('index', 'cpplot.tex', u'cpplot',
+ u'Tom Clark', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+# latex_use_parts = False
+
+# If true, show page references after internal links.
+# latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+# latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+# latex_appendices = []
+
+# If false, no module index is generated.
+# latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'cpplot', u'cpplot',
+ [u'Tom Clark'], 1)
+]
+
+# If true, show URL addresses after external links.
+# man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ ('index', 'cpplot', u'cpplot',
+ u'Tom Clark', 'cpplot', 'JSON based figures for C++',
+ 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+# texinfo_appendices = []
+
+# If false, no module index is generated.
+# texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+# texinfo_show_urls = 'footnote'
diff --git a/docs/source/favicon.ico b/docs/source/favicon.ico
new file mode 100644
index 0000000..97f2f38
Binary files /dev/null and b/docs/source/favicon.ico differ
diff --git a/docs/source/images/digital_twin_component_basic.svg b/docs/source/images/digital_twin_component_basic.svg
new file mode 100644
index 0000000..b49800f
--- /dev/null
+++ b/docs/source/images/digital_twin_component_basic.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..c72642b
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,43 @@
+|pre-commit| |black-girls-code|
+
+.. ATTENTION::
+ This library is in use in several projects, but it's still early days.
+ Like the idea of it? Please
+ `star us on GitHub `_ and contribute via the
+ `issues board `_ and
+ `roadmap `_.
+
+
+======
+cpplot
+======
+
+.. epigraph::
+ *"cpplot" ~ interactive figures you can show on the web*
+
+This library allows you to create interactive graphs and charts in C++ 11 upward, which are
+`viewable in-browser `_.
+
+You can save figures to disc as ``\*.json`` files. Their contents are compliant with the
+``plotly.js`` library schema so figures can be rendered in javascript.
+
+Get going with the :ref:`quick start<_quick_start>`, or :ref:`read about why I started this<_why>`...
+
+Contents
+========
+
+.. toctree::
+ :maxdepth: 2
+
+ quick_start
+ installation
+ about
+ license
+ library_api/library_root
+ version_history
+
+
+.. |pre-commit| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
+ :target: https://github.com/pre-commit/pre-commit
+.. |black-girls-code| image:: https://img.shields.io/badge/black%20girls-code-f64279.svg
+ :target: https://www.blackgirlscode.com/
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
new file mode 100644
index 0000000..44acd93
--- /dev/null
+++ b/docs/source/installation.rst
@@ -0,0 +1,61 @@
+.. _installation:
+
+============
+Installation
+============
+
+.. ATTENTION::
+ `We're working on it. I promise. `_
+
+ Until we get conan or vcpkg up and running, installation is via cmake.
+
+.. _upgrading_from_previous_versions:
+
+Upgrading from previous versions
+================================
+
+Please see the note on version stability and backward compatibility :ref:`here<_stability>`.
+
+
+.. _third_party_dependencies:
+
+Third party dependencies
+========================
+
+Install and link
+----------------
+
+`**Eigen** `__ 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.
+
+`**glog** `__ google's asynchronous
+logging library, used for logging to file.
+
+`**googletest** `__ for unit
+testing.
+
+
+Submodule dependencies
+----------------------
+
+We also use `cpr `__ and `json `__, which are included as submodule dependencies.
+
+**THIS WILL CHANGE VERY SOON!** But for now, you'll need to clone the repository **and its submodules, cpr and
+json,** in order to build it.
+
+.. code:: bash
+
+ git clone --recurse-submodules https://github.com/thclark/cpplot
+
+
+.. _compilation_with_cmake:
+
+Compilation with cmake
+======================
+
+A cross-platform compilation file is provided using cmake, but it's
+**not tested on windows**.
+
+PRs to fix or improve it for windows are most welcome.
diff --git a/docs/source/license.rst b/docs/source/license.rst
new file mode 100644
index 0000000..e8dbbc2
--- /dev/null
+++ b/docs/source/license.rst
@@ -0,0 +1,20 @@
+.. _license:
+
+=======
+License
+=======
+
+
+The boring bit
+==============
+
+Your license here.
+
+
+Third Party Libraries
+=====================
+
+**cpplot** includes or is linked against the following third party libraries:
+
+Stuff here.
+
diff --git a/docs/source/quick_start.rst b/docs/source/quick_start.rst
new file mode 100644
index 0000000..fac4e1e
--- /dev/null
+++ b/docs/source/quick_start.rst
@@ -0,0 +1,97 @@
+.. _quick_start:
+
+===========
+Quick Start
+===========
+
+.. _viewing_figures:
+
+Viewing Figures
+===============
+
+A browser based viewer is supplied at `https://cpplot.herokuapp.com `__.
+Navigate to that link and you'll be able to view and export figures created with **cpplot**.
+
+The viewer always keeps your data local (files are never uploaded to a server).
+
+If you've not created figure files yourself yet, you can
+`download the examples from here `__
+and then select them in the viewer. Some are simple, some are amazing ;)
+
+
+.. _create_your_first_figure:
+
+Create Your First Figure
+========================
+
+To create your first figure with **cpplot**, you can compile and run the program below:
+
+.. code-block:: cpp
+
+ /*
+ * main.cpp - An example program to create your first figure as a Plotly-compliant .json file.
+ *
+ * Author: YOU
+ *
+ * Copyright (c) YEAR YOU. All Rights Reserved.
+ *
+ */
+ #include
+ #include
+ #include
+ #include "cpplot.h" // TODO these may need to change to something like for users
+ #include "eigen.h" // who have installed the library rather than linking against source code
+ #include "exceptions.h" // directly
+
+ using namespace std;
+ using namespace Eigen;
+ using namespace cpplot;
+
+ int main(int argc, char* argv[]) {
+
+ // Create a figure object
+ Figure fig = Figure();
+
+ // Create a scatter plot object and set its values
+ ScatterPlot p1 = ScatterPlot();
+ p1.x = Eigen::VectorXd::LinSpaced(10, 0.0, 1.0);
+ p1.y = Eigen::VectorXd::LinSpaced(10, 1.0, 2.0);
+
+ // Alter its properties
+ p1.name = "my first trace";
+ p.setWidth(1);
+ p.setDash("dash");
+ p.setColor("#e377c2"); // "Raspberry yoghurt pink", obviously the best selection
+
+ // Add it to the figure
+ fig.add(p1);
+
+ // You can add multiple plots to a figure...
+ ScatterPlot p2 = ScatterPlot();
+ p2.name = "my second trace";
+ fig.add(p2);
+
+ // And whenever you want, you can write a figure to disc.
+ // Note, writing is an async task so your calculations can
+ // proceed whilst writing goes into the background.
+ //
+ // In this example we allow the write() method to automatically append a `.json` extension
+ // to the file name (if not already present), and we prevent it from printing the json to stdout
+ // (which can be a useful feature to enable if you want to use your program with bash pipes)
+ std::cout << "Writing figure to current directory: " << std::endl;
+ fig.write("my_first_cpplot_figure", true, false);
+
+ }
+
+
+.. _building_web_tools:
+
+Building Your Own Web Tools
+===========================
+
+You (or the frontend team you work with!) will probably want to display figures in your own web tools, rather than
+always our (fairly basic, right now) viewer utility.
+
+The `browser viewer `__ is built in React (using ``react-plotly.js``).
+It is also open-source, so you can use its components as a basis for your own. See
+`https://github.com/thclark/cpplot-viewer `__
diff --git a/docs/source/version_history.rst b/docs/source/version_history.rst
new file mode 100644
index 0000000..248eef5
--- /dev/null
+++ b/docs/source/version_history.rst
@@ -0,0 +1,59 @@
+.. _version_history:
+
+===============
+Version History
+===============
+
+.. _origins:
+
+Origins
+=======
+
+This library was hacked together / extracted from other repositories such as `the es-flow library `__ due to the
+need for a plotting library enabling me to deliver results over the web.
+
+As more stars are being added on GitHub (14 at the time of writing, woot woot!) it's now worth properly versioning
+and maintaining the effort, since it seems like it's useful to more people than just me.
+
+.. _stability:
+
+Stability
+=========
+
+The library uses semver versioning, like `version x.y.z`.
+
+Theoretically, only `x` increments should break backward compatibility. But, it's still early days as noted in
+`issue 10 `__ and I don't want to end up on version 200.4.5 in
+the next five minutes...
+
+**Let's be pragmatic:** whilst still on version `0.0.z` please consider the API as unstable
+version-to-version (z increments). This is because I (or we -
+`please help `_!) will be still architecting the library sensibly.
+
+**When I break it, I'll at least tell you what's breaking! Check back here as you update.**
+
+For `versions >= 0.x.y` expect `y` increments not to break, breaking changes might occur on `x` increments.
+
+For `versions >= x.y.z` where `x >= 1` expect `x` increments to break backward compatibility.
+
+
+.. _version_0.0.1:
+
+0.0.1
+=====
+
+Initial version applied to the library
+
+New Features
+------------
+#. Documentation in RestructuredText and hooked for public viewing on `readthedocs