docs(bff): add plots and examples in documentation

Closes #18.
axelfahy · Aug 29, 2019 · bad16c2 · bad16c2
1 parent fcbf75e
commit bad16c2
Show file tree

Hide file tree

Showing 27 changed files with 1,025 additions and 11 deletions.
diff --git a/.gitignore b/.gitignore
@@ -73,7 +73,6 @@ instance/
 doc/_build
 doc/build
 doc/source/generated
-doc/source/_static
 
 # PyBuilder
 target/

diff --git a/Makefile b/Makefile
@@ -7,12 +7,23 @@ all: test
 build-python:
 	python setup.py sdist bdist_wheel
 
+.PHONY: build-notebook
+build-notebook:
+	# Convert .ipynb to rst file. Needs pandoc installed.
+	jupyter nbconvert --to rst notebooks/notebook-bff-plot.ipynb
+
 .PHONY: clean
 clean:
 	rm -rf coverage_html_report .coverage
 	rm -rf bff.egg-info
 	rm -rf venv-dev
 	rm -rf dist/
+	rm -rf notebooks/notebook-bff-plot_files/
+
+.PHONY: clean-notebooks
+clean-notebooks:
+	# Corrections of path to images in notebook export.
+	sed -i 's/\.\. image:: /\.\. image:: \.\.\/\.\.\/notebooks\//g' notebooks/notebook-bff-plot.rst
 
 .PHONY: test
 test: code lint style coverage

diff --git a/README.md b/README.md
@@ -53,6 +53,7 @@ As of *v0.2*, plots are not yet tested in the travis build.
 * 0.2.0
     * ADD: Separation of plots in submodule ``plot``. This breaks the previous API.
     * ADD: Tests for the plot module using ``pytest-mlp``.
+    * ADD: Images from plot in the documentation and notebook with examples.
     * FIX: Correction of resampling in the ``plot_series`` function.
 * 0.1.9
     * ADD: Option ``loc`` in ``plot_series`` function.

diff --git a/doc/README.md b/doc/README.md
@@ -6,3 +6,11 @@
 make html
 ```
 
+## Convert the notebooks to rst files
+
+From main makefile of project:
+
+```sh
+make build-notebook
+```
+
diff --git a/doc/source/_static/style.css b/doc/source/_static/style.css
@@ -0,0 +1,3 @@
+.wy-nav-content {
+    max-width: none;
+}
diff --git a/doc/source/_templates/layout.html b/doc/source/_templates/layout.html
@@ -0,0 +1,4 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+    <link href="{{ pathto("_static/style.css", True) }}" rel="stylesheet" type="text/css">
+{% endblock %}
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -38,8 +38,10 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'nbsphinx',                 # Needed to import notebooks.
     'recommonmark',
     'sphinx.ext.autodoc',
+    'sphinx.ext.mathjax',
     'sphinx.ext.napoleon',      # Needed to separate type from variable name in docstrings.
     'sphinx_autodoc_typehints', # Need to be imported after `sphinx.ext.napoleon`.
     'numpydoc',
@@ -53,7 +55,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ['**.ipynb_checkpoints']
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -66,7 +68,7 @@
 # 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 = []
+html_static_path = ['_static']
 
 # Theme from Read the Docs.
 html_theme_options = {

diff --git a/doc/source/example_plots.rst b/doc/source/example_plots.rst
@@ -0,0 +1 @@
+.. include::   ../../notebooks/notebook-bff-plot.rst
diff --git a/doc/source/fancy.rst b/doc/source/fancy.rst
@@ -13,10 +13,10 @@ All of bff's functions.
    bff.idict
    bff.mem_usage_pd
    bff.parse_date
-   bff.plot_history
-   bff.plot_predictions
-   bff.plot_series
-   bff.plot_true_vs_pred
+   bff.plot.plot_history
+   bff.plot.plot_predictions
+   bff.plot.plot_series
+   bff.plot.plot_true_vs_pred
    bff.read_sql_by_chunks
    bff.sliding_window
    bff.value_2_list

diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -12,10 +12,25 @@ The bff package contains some utility functions from plots to data manipulations
 
 The goal of this package is to have easy access of the functions I am using frequently on projects.
 
-This is still a work in progress, contributions are welcome.
 
-Contents
---------
+.. |history_with_metric| image:: ../../tests/baseline/test_plot_history_with_metric.png
+   :width: 30%
+   :align: middle
+   :alt: History with metric
+
+.. |series_peaks| image:: ../../tests/baseline/test_plot_series_with_peaks.png
+   :width: 30%
+   :align: middle
+   :alt: Series with peaks
+
+.. |true_vs_pred| image:: ../../tests/baseline/test_plot_true_vs_pred_default.png
+   :width: 30%
+   :align: middle
+   :alt: True vs prediction
+
+|history_with_metric| |series_peaks| |true_vs_pred|
+
+This is still a work in progress, contributions are welcome.
 
 .. toctree::
    :maxdepth: 2

diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst
@@ -10,15 +10,46 @@ If you use ``pip``, you can install it with::
 
     pip install bff
 
+Examples
+--------
+
+Here are some examples of possible plots from the `plot` module.
+
+.. toctree::
+   :maxdepth: 2
+
+   example_plots
+
 Development
 -----------
 
+Setup
+~~~~~
+
+The developement environment can be installed as follow:
+
+.. code-block:: bash
+
+   git clone https://github.com/axelfahy/bff.git
+   cd bff
+   python -m venv venv-dev
+   source venv-dev/bin/activate
+   pip install -r requirements_dev.txt
+   pip install -e .
+
+Unittest
+~~~~~~~~
+
 You can run the test using::
 
-    make all
+   make all
 
 This will run unittests for code and code style checks.
 
+To test plots, images with baseline should be placed in `tests/baseline` and can be generated using :code:`make build-baseline`.
+
+As of *v0.2*, plots are not yet tested in the travis build.
+
 Contributing
 ------------
 

diff --git a/notebooks/notebook-bff-plot.ipynb b/notebooks/notebook-bff-plot.ipynb
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		.. include:: ../../notebooks/notebook-bff-plot.rst