Merge pull request #2 from mpewsey/dev

Documentation updates

Author: mpewsey

.gitignore

@@ -9,6 +9,7 @@ __pycache__/
 .pytest_cache
 
 /docs/index.md
+docs/generated
 
 # Distribution / packaging
 .Python

README.md

@@ -2,15 +2,9 @@
 
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/error_solver.svg)
 ![PyPI](https://img.shields.io/pypi/v/error_solver.svg)
-[![Build Status](https://travis-ci.com/line-mind/error_solver.svg?branch=master)](https://travis-ci.com/line-mind/error_solver)
+[![Build Status](https://travis-ci.com/mpewsey/error_solver.svg?branch=master)](https://travis-ci.com/mpewsey/error_solver)
 [![Documentation Status](https://readthedocs.org/projects/error-solver/badge/?version=latest)](https://error-solver.readthedocs.io/en/latest/?badge=latest)
-[![codecov](https://codecov.io/gh/line-mind/error_solver/branch/master/graph/badge.svg)](https://codecov.io/gh/line-mind/error_solver)
-
-<!--
-## Table of Contents
-
-* [Error Solver](error_solver.rst)
--->
+[![codecov](https://codecov.io/gh/mpewsey/error_solver/branch/master/graph/badge.svg)](https://codecov.io/gh/mpewsey/error_solver)
 
 ## About
 
@@ -32,15 +26,3 @@ The above installation only install the dependencies required for the
 ```
 pip install error_solver[all]
 ```
-
-<!--
-## Example: Error in Cylinder
-
-The below example determines the propagation error tolerances for the cross
-sectional area `A` and volume `V` of a cylinder given the
-measurement tolerance for the radius `r` and height `h`.
-
-```eval_rst
-.. literalinclude:: ../examples/error_solver_ex1.py
-```
--->

docs/_templates/autosummary/class.rst

@@ -0,0 +1,17 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: Methods
+
+   .. autosummary::
+      :toctree:
+   {% for item in methods %}
+      {% if item not in ['__init__', 'get', 'copy', 'clear', 'fromkeys', 'items', 'keys', 'pop', 'popitem', 'setdefault', 'update', 'values', 'getfield', 'partition', 'all', 'any', 'argmax', 'argmin', 'argpartition', 'argsort', 'astype', 'byteswap', 'choose', 'clip', 'compress', 'conj', 'conjugate', 'cumprod', 'cumsum', 'diagonal', 'dot', 'dump', 'dumps', 'fill', 'flatten', 'item', 'itemset', 'max', 'mean', 'min', 'newbyteorder', 'nonzero', 'portition', 'prod', 'ptp', 'put', 'ravel', 'repeat', 'reshape', 'resize', 'round', 'searchsorted', 'setfield', 'setflags', 'sort', 'squeeze', 'std', 'sum', 'swapaxes', 'take', 'tobytes', 'tofile', 'tolist', 'tostring', 'trace', 'transpose', 'var', 'view'] %}~{{ name }}.{{ item }}{% endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/_templates/index.md

@@ -0,0 +1,14 @@
+{%- if pagename != "search" and builder != "singlehtml" %}
+<div id="searchbox" style="display: none" role="search">
+  <h4>{{ _('Quick search') }}</h4>
+    <div>
+    <form class="search" action="{{ pathto('search') }}" method="get">
+      <input type="text" style="width: inherit;" name="q" placeholder="Search"/>
+      <!--<input type="submit" value="{{ _('search') }}" />-->
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+    </div>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+{%- endif %}

docs/_templates/searchbox.html

@@ -18,51 +18,32 @@
 
 import os
 import sys
+import shutil
 from configparser import ConfigParser
-from recommonmark.transform import AutoStructify
-from recommonmark.parser import CommonMarkParser
-from jinja2 import Environment, FileSystemLoader, StrictUndefined
 
 root = os.path.abspath(os.path.join('..'))
 sys.path.insert(0, root)
 
 # Load metadata from setup.cfg
-metadata_file = os.path.join(root, 'setup.cfg')
-metadata = ConfigParser()
-metadata.read(metadata_file)
-metadata = metadata['metadata']
-
-with open(os.path.join(root, 'README.md'), 'rt') as fh:
-    metadata['long_description'] = fh.read()
-
-# Render index.md with metadata
-def write_index():
-    path = os.path.join(root, 'docs', '_templates')
-    env = Environment(loader = FileSystemLoader(path),
-                      undefined = StrictUndefined)
-    template = env.get_template('index.md')
-    s = template.render(**metadata)
-    s = s.replace('<!--', '')
-    s = s.replace('-->', '')
-    
-    with open(os.path.join(root, 'docs', 'index.md'), 'wt') as fh:
-        fh.truncate()
-        fh.write(s)
-
-write_index()
+meta_path = os.path.join(root, 'setup.cfg')
+meta = ConfigParser()
+meta.read(meta_path)
+meta = meta['metadata']
+
+# Clear generated documents
+if (not os.path.exists('_build') or len(os.listdir('_build')) == 0) and os.path.exists('generated'):
+    shutil.rmtree('generated')
 
 # -- Project information -----------------------------------------------------
 
-project = metadata['project']
-copyright = metadata['copyright']
-author = metadata['author']
+project = meta['project']
+copyright = meta['copyright']
+author = meta['author']
 
 # The short X.Y version
-version = metadata['version']
+version = meta['version']
 # The full version, including alpha/beta/rc tags
-release = metadata['version']
-
-github_doc_root = 'https://github.com/line-mind/{}/tree/master/'.format(metadata['name'])
+release = meta['version']
 
 # -- General configuration ---------------------------------------------------
 
@@ -74,6 +55,7 @@ def write_index():
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    #'matplotlib.sphinxext.plot_directive',
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
@@ -84,7 +66,7 @@ def write_index():
     'numpydoc',
     #'sphinx.ext.imgmath',
     'sphinx.ext.viewcode',
-    'sphinx.ext.githubpages',
+    #'sphinxcontrib.spelling',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -96,10 +78,6 @@ def write_index():
 source_suffix = ['.rst', '.md']
 #source_suffix = '.rst'
 
-source_parsers = {
-   '.md' : CommonMarkParser
-}
-
 # The master toctree document.
 master_doc = 'index'
 
@@ -125,6 +103,7 @@ def write_index():
 # a list of builtin themes.
 #
 themedir = os.path.join(os.path.dirname(__file__), 'scipy-sphinx-theme', '_theme')
+
 if not os.path.isdir(themedir):
     raise RuntimeError('Get the scipy-sphinx-theme first, '
                        'via git submodule init && git submodule update')
@@ -137,14 +116,16 @@ def write_index():
 numpydoc_show_class_members = False
 numpydoc_show_inherited_class_members = False
 class_members_toctree = False
+autosummary_generate = True
 
 html_theme_options = {
     "edit_link": False,
     "sidebar": "left",
     "scipy_org_logo": False,
     "rootlinks": []
 }
-html_sidebars = {}
+
+html_sidebars = {'index': ['searchbox.html']}
 
 html_title = "%s v%s Manual" % (project, version)
 html_last_updated_fmt = '%b %d, %Y'
@@ -174,7 +155,7 @@ def write_index():
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = '{}_doc'.format(metadata['name'])
+htmlhelp_basename = '{}'.format(meta['name'])
 
 
 # -- Options for LaTeX output ------------------------------------------------
@@ -203,7 +184,7 @@ def write_index():
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, '{}.tex'.format(metadata['name']), '{} Documentation'.format(metadata['project']),
+    (master_doc, '{}.tex'.format(meta['name']), '{} Documentation'.format(meta['project']),
      author, 'manual'),
 ]
 
@@ -213,7 +194,7 @@ def write_index():
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, metadata['name'], '{} Documentation'.format(metadata['project']),
+    (master_doc, meta['name'], '{} Documentation'.format(meta['project']),
      [author], 1)
 ]
 
@@ -224,8 +205,8 @@ def write_index():
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, metadata['name'], '{} Documentation'.format(metadata['project']),
-     author, metadata['name'], metadata['description'],
+    (master_doc, meta['name'], '{} Documentation'.format(meta['project']),
+     author, meta['name'], meta['description'],
      'Miscellaneous'),
 ]
 
@@ -235,17 +216,14 @@ def write_index():
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://docs.scipy.org/doc/numpy/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+    'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
+}
 
 # -- Options for todo extension ----------------------------------------------
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
-
-# AutoStructify setup
-def setup(app):
-    app.add_config_value('recommonmark_config', {
-            'url_resolver': lambda url: github_doc_root + url,
-            'auto_toc_tree_section': 'Table of Contents',
-            }, True)
-    app.add_transform(AutoStructify)

docs/conf.py

@@ -0,0 +1,58 @@
+=========================
+Error Solver Documenation
+=========================
+
+.. image:: https://img.shields.io/pypi/pyversions/error_solver.svg
+    :target: #
+
+.. image:: https://img.shields.io/pypi/v/error_solver.svg
+    :target: #
+
+.. image:: https://travis-ci.com/mpewsey/error_solver.svg?branch=master
+    :target: https://travis-ci.com/mpewsey/error_solver
+
+.. image:: https://readthedocs.org/projects/error-solver/badge/?version=latest
+    :target: https://error-solver.readthedocs.io/en/latest/?badge=latest
+
+.. image:: https://codecov.io/gh/mpewsey/error_solver/branch/master/graph/badge.svg
+    :target: https://codecov.io/gh/mpewsey/error_solver
+
+About
+=====
+This package contains classes for estimating the propagation error tolerances
+for a system of equations.
+
+Installation
+============
+
+This package may be installed via pip:
+
+.. code-block:: none
+
+    pip install error_solver
+
+
+The above installation only install the dependencies required for the
+`ErrorSolverPy` class. To also install the dependencies necessary for the
+`ErrorSolver` class, use the following command instead:
+
+.. code-block:: none
+
+    pip install error_solver[all]
+
+
+Example: Error in Cylinder
+==========================
+The below example determines the propagation error tolerances for the cross
+sectional area `A` and volume `V` of a cylinder given the
+measurement tolerance for the radius `r` and height `h`.
+
+.. literalinclude:: ../examples/error_solver_ex1.py
+
+
+API Documentation
+=================
+.. toctree::
+    :maxdepth: 1
+
+    error_solver

docs/index.rst

@@ -1,15 +1,20 @@
 """
-==================================
-Error Solver (:mod:`error_solver`)
-==================================
+===================================
+Error Solver (:mod:`.error_solver`)
+===================================
 
-.. automodule:: error_solver.error_solver
-    :members:
-    :inherited-members:
+The below classes are available for error propagation approximation.
 
-.. automodule:: error_solver.error_solver_py
-    :members:
-    :inherited-members:
+.. autosummary::
+    :toctree: generated/
+
+    ErrorSolver
+    ErrorSolverPy
 """
 
+try:
+    from .error_solver import *
+except:
+    pass
+
 from .error_solver_py import *

error_solver/__init__.py

@@ -1,11 +1,3 @@
-"""
-==========================================================
-Base Error Solver (:mod:`error_solver._base_error_solver`)
-==========================================================
-
-Contains a class used as the base for ErrorSolver and ErrorSolverPy.
-"""
-
 import numpy as np
 import pandas as pd