Merge pull request #106 from chrisjsewell/develop

Release v0.10.9

docs/source/dev_guide.rst

@@ -0,0 +1,76 @@
+Developer Guide
++++++++++++++++
+
+Installation
+~~~~~~~~~~~~
+
+To install the development version::
+
+    >> git clone https://github.com/chrisjsewell/ipypublish .
+    >> cd ipypublish
+
+and either use the pre-written Conda development environment (recommended)::
+
+    >> conda env create -n ipub_testenv -f conda_dev_env.yaml python=3.6
+    >> conda activate ipub_testenv
+    >> pip install --no-deps -e .
+
+or install all *via* pip::
+
+    >> pip install -e .[tests]
+
+Testing
+~~~~~~~
+
+|Build Status| |Coverage Status|
+
+The following will discover and run all unit test:
+
+.. code:: shell
+
+   >> cd ipypublish
+   >> pytest -v
+
+Coding Style Requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The code style is tested using `flake8 <http://flake8.pycqa.org>`__,
+with the configuration set in ``.flake8``, and code should be formatted
+with `yapf <https://github.com/google/yapf>`__ (configuration set in
+``.style.yapf``).
+
+Installing with ``ipypublish[tests]`` makes the
+`pre-commit <https://pre-commit.com/>`__ package available, which will
+ensure these tests are passed by reformatting the code and testing for
+lint errors before submitting a commit. It can be setup by:
+
+.. code:: shell
+
+   >> cd ipypublish
+   >> pre-commit install
+
+Optionally you can run ``yapf`` and ``flake8`` separately:
+
+.. code:: shell
+
+   >> yapf -i path/to/file  # format file in-place
+   >> flake8
+
+Editors like VS Code also have automatic code reformat utilities, which
+can check and adhere to this standard.
+
+Documentation
+~~~~~~~~~~~~~
+
+The documentation can be created locally by:
+
+.. code:: shell
+
+   >> cd ipypublish/docs
+   >> make clean
+   >> make  # or make debug
+
+.. |Build Status| image:: https://travis-ci.org/chrisjsewell/ipypublish.svg?branch=master
+   :target: https://travis-ci.org/chrisjsewell/ipypublish
+.. |Coverage Status| image:: https://coveralls.io/repos/github/chrisjsewell/ipypublish/badge.svg?branch=master
+   :target: https://coveralls.io/github/chrisjsewell/ipypublish?branch=master

docs/source/index.rst

@@ -13,10 +13,12 @@ and presentations, from Jupyter Notebooks.
 
 .. attention::
 
-    IPyPublish has evolved!
-
+    IPyPublish is evolving!
     Please see :ref:`releases` for all the exciting new feature.
 
+    Also see `pytest-notebook <https://pytest-notebook.readthedocs.io>`_,
+    for a new tool to test and regenerate notebooks.
+
 
 IPyPublish: Features
 ====================
@@ -54,33 +56,48 @@ Badges
 |Build Status| |Coverage Status| |PyPI| |Conda|
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :numbered:
-   :caption: Contents:
+   :caption: Using IPyPublish
+   :hidden:
 
    getting_started
    code_cells
    markdown_cells
    nb_conversion
    metadata_tags
    custom_export_config
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Sphinx Extensions
+   :hidden:
+
    sphinx_extensions
+   sphinx_ext_notebook
+   sphinx_ext_bibgloss
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Additional Information
+   :hidden:
+
+   releases
    examples
    applications
+   dev_guide
    additional_tools
    acknowledgements
    package_api
-   releases
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Included Files:
+   :maxdepth: 1
+   :caption: Validation Schemas
+   :hidden:
 
-   latex_ipypublish_all
-   export_schema
-   outline_schema
-   segment_example
    metadata_doc_schema
+   metadata_cell_schema
+   export_schema
 
 
 .. todo:: how to use with vs-code

docs/source/latex_ipypublish_all.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 .. _latex_ipypublish_all:
 
 Example Export Configuration

docs/source/markdown_cells.Rmd

@@ -10,7 +10,7 @@ jupyter:
       author: Chris Sewell
       email: chrisj\_sewell@hotmail.com
       logo: _static/logo_example.png
-      title: Example of Converted Jupyter Notebook 
+      title: Example of Converted Jupyter Notebook
       subtitle: Formatting Markdown Cells
       tagline: Converted using IPyPublish ('latex\_ipypublish\_all.exec').
       supervisors:
@@ -20,7 +20,7 @@ jupyter:
       - Institution1
       - Institution2
     pandoc:
-      convert_raw: true 
+      convert_raw: true
       hide_raw: false
       at_notation: true
       use_numref: true
@@ -61,7 +61,7 @@ This filter extends the common markdown syntax to:
 - Correctly translate pieces of documentation written in other formats
   (such as using LaTeX commands like `\cite` or RST roles like `:cite:`)
 - Handle labelling and referencing of figures, tables and equations, and
-  add additional formatting options. 
+  add additional formatting options.
 
 `ipubpandoc` is detached from the rest of the
 notebook conversion process, and so can be used as a standalone process on any markdown content:
@@ -74,6 +74,8 @@ $ pandoc -f markdown -t html --filter ipubpandoc path/to/file.md
 
     [The PDF representation of this notebook](_static/markdown_cells.pdf)
 
+    :ref:`pandoc_doc_metadata`, for the notebook document level metadata options.
+
 .. _jupytext_rmarkdown:
 
 ## Converting Notebooks to RMarkdown
@@ -309,7 +311,7 @@ Glossary Terms: %@gtkey2, &@akey2, &@symbol2
 
 .. note::
 
-    Citations in sphinx are provided by the excellent 
+    Citations in sphinx are provided by the excellent
     [sphinxcontrib-bibtex extension](https://sphinxcontrib-bibtex.readthedocs.io),
     and glossary referencing is provided by the equally good :ref:`sphinx_ext_gls`
 
@@ -384,10 +386,10 @@ data-latex="cref" data-rst="numref" data-a="1">
 <span class="citation" data-cites="label">
 @label
 </span></span>
-xyz 
+xyz
 <em><span class="citation" data-cites="label2">
 @label2
-</span></em> 
+</span></em>
 <span class="attribute-Cite b">
 <span class="citation" data-cites="label3">
 @label3
@@ -396,4 +398,4 @@ xyz
 ```
 
 Formatter filters, then look for these parent spans,
-to provide identifiers, classes and attributes.
+to provide identifiers, classes and attributes.

docs/source/metadata_cell_schema.rst

@@ -0,0 +1,7 @@
+.. _meta_celllevel_schema:
+
+Cell/Output Level Metadata Schema
+---------------------------------
+
+.. literalinclude:: ../../ipypublish/schema/cell_metadata.schema.json
+  :language: JSON