Updated for scipy sphinx theme

Author: mpewsey

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs/scipy-sphinx-theme"]
+	path = docs/scipy-sphinx-theme
+	url = https://github.com/scipy/scipy-sphinx-theme

README.md

@@ -1,49 +1,34 @@
 # PLSXML
 
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/plsxml.svg)
 ![PyPI](https://img.shields.io/pypi/v/plsxml.svg)
 [![Build Status](https://travis-ci.com/line-mind/plsxml.svg?branch=master)](https://travis-ci.com/line-mind/plsxml)
 [![Documentation Status](https://readthedocs.org/projects/plsxml/badge/?version=latest)](https://plsxml.readthedocs.io/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/line-mind/plsxml/branch/master/graph/badge.svg)](https://codecov.io/gh/line-mind/plsxml)
 
 
-## Contents
-
-### API Contents
-
-* [About](#about)
-* [Installation](#installation)
-* [Example Usage](#example-usage)
-
-### Developer Contents
-
-* [Local Testing](#local-testing)
-
-### Module Contents
+## Table of Contents
 
 * [PLSXML](plsxml.rst)
-* [Data Loader](data.rst)
-
-## API Notes
+* [Data](data.rst)
 
-### About
+## About
 
 This package provides a class for parsing PLS-CADD XML files to dictionaries and `pandas` data frames. It is also capable of converting elements with 'units' attributes to `astropy` quantities, though currently this package may not be able to handle all units.
 
-### Installation
+## Installation
 
 This package may be installed via pip:
 
 ```
 pip install plsxml
 ```
 
-### Example Usage
-
-See [example.ipynb](example.ipynb) for example usages of this package.
+## Example Usage
 
-## Developer Notes
+See [example.ipynb](https://github.com/line-mind/plsxml/blob/master/example.ipynb) for example usages of this package.
 
-### Local Testing
+## Local Testing
 
 Testing is performed using `pytest` and `pytest-cov`. To test the package locally,
 run the following command from the root directory:

docs/conf.py

@@ -85,8 +85,6 @@ def write_index():
     'sphinx.ext.githubpages',
 ]
 
-numpydoc_show_inherited_class_members = False
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -113,7 +111,7 @@ def write_index():
 # 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 = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'scipy-sphinx-theme/*']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -124,8 +122,30 @@ def write_index():
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
-html_theme_path = ['_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')
+
+
+html_theme = 'scipy'
+html_theme_path = [themedir]
+
+# numpydoc settings
+numpydoc_show_class_members = False
+numpydoc_show_inherited_class_members = False
+class_members_toctree = False
+
+html_theme_options = {
+    "edit_link": False,
+    "sidebar": "left",
+    "scipy_org_logo": False,
+    "rootlinks": []
+}
+html_sidebars = {}
+
+html_title = "%s v%s Manual" % (project, version)
+html_last_updated_fmt = '%b %d, %Y'
 
 # 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
@@ -224,6 +244,6 @@ def write_index():
 def setup(app):
     app.add_config_value('recommonmark_config', {
             'url_resolver': lambda url: github_doc_root + url,
-            'auto_toc_tree_section': 'Module Contents',
+            'auto_toc_tree_section': 'Table of Contents',
             }, True)
     app.add_transform(AutoStructify)

docs/scipy-sphinx-theme

@@ -64,7 +64,7 @@
    "source": [
     "## Listing Keys\n",
     "\n",
-    "Calling the `PLSXML.keys()` method will provide a list of parsed tables, keys, and example data. This may be useful when determining which tables and data you want to work with. An example output is below:"
+    "Calling the `table_summary` method will provide a list of parsed tables, keys, and example data. This may be useful when determining which tables and data you want to work with. An example output is below:"
    ]
   },
   {

example.ipynb

@@ -1,7 +1,7 @@
 """
-=================================
-Data Loaders (:mod:`plsxml.data`)
-=================================
+=========================
+Data (:mod:`plsxml.data`)
+=========================
 
 .. automodule:: plsxml.data.loader
   :members:

plsxml/data/__init__.py

@@ -1,5 +1,16 @@
 """
-The PLSXML data module contains sample and test data.
+Summary
+-------
+The PLSXML data module contains methods for accessing sample and test data.
+
+Global Variables
+----------------
+DATA_FOLDER
+    The absolute path to the data directory.
+
+Methods
+-------
+
 """
 
 import os

plsxml/data/loader.py

@@ -1,39 +1,39 @@
 """
+Summary
+-------
 The PLSXML module contains a class for parsing PLS-CADD XML files.
+
+Classes
+-------
+
 """
 
 import ast
 from collections import OrderedDict
-import xml.etree.ElementTree as et
+import xml.etree.cElementTree as et
 import pandas as pd
 import astropy.units as u
 u.imperial.enable()
 
 
 class PLSXML(OrderedDict):
     """
-    A class for parsing PLS-CADD XML files. Data can be accessed using
-    via table name -> row index -> column name. Example:
-
-    .. code::
-
-        PLSXML['galloping_ellipses_summary'][0]['phase']
-
+    A class for parsing PLS-CADD XML files.
 
     Parameters
     ----------
-    source : str or list
+    source : str or list, default is None
         A string or list of strings defining the XML file path(s).
         If None, then no tables will be parsed.
-    tables : list
+    tables : list, default is None
         A list of strings defining the table names to be loaded from the
         referenced XML files. If None, then all tables in the XML files
         will be parsed.
-    parse_units : bool
+    parse_units : bool, default is False
         If True, elements with the 'units' attribute will attempt to be
         converted to Astropy quantities. This operation takes longer so could
         be disabled if including units is unimportant to you.
-    print_statuses : bool
+    print_statuses : bool, default is False
         If True, status messages will be printed during the parsing process.
         This can be useful to see the progress of long XML files.
 
@@ -50,11 +50,45 @@ class PLSXML(OrderedDict):
     --------
     >>> from plsxml import PLSXML
     >>> from plsxml.data import data_path
+
+    To load data from the intializer:
+
     >>> path = data_path('galloping')
     >>> xml = PLSXML(path, parse_units = True)
+
+    You can add files after the initialization via the `append` method:
+
+    >>> xml = PLSXML(parse_units = True)
+    >>> xml.append(path)
+
+    The class is a subclass of an OrderedDict. Once loaded, data can be accessed
+    via table name > row index > column name:
+
     >>> xml['galloping_ellipses_summary'][0]['minimum_clearance_galloping_ellipse_method']
     'Single mid span'
 
+    A summary of keys can be acquired via the `table_summary` method:
+
+    >>> print(xml.table_summary())
+    galloping_ellipses_summary
+	rowtext                                                     	None
+	structure                                                   	'TERM'
+	set                                                         	1
+	phase                                                       	1
+	ahead_span_length                                           	258.2 ft
+	minimum_clearance_set                                       	1
+	minimum_clearance_phase                                     	2
+	minimum_clearance_galloping_ellipse_method                  	'Single mid span'
+	minimum_clearance_distance                                  	1.52 ft
+	minimum_clearance_overlap                                   	0.0
+	minimum_clearance_wind_from                                 	'Left'
+	minimum_clearance_mid_span_sag                              	12.15 ft
+	minimum_clearance_insulator_swing_angle                     	0.0 deg
+	minimum_clearance_span_swing_angle                          	63.1 deg
+	minimum_clearance_major_axis_length                         	16.2 ft
+	minimum_clearance_minor_axis_length                         	6.5 ft
+	minimum_clearance_b_distance                                	3.0 ft
+
     """
     def __init__(self, source = None, tables = None, parse_units = False, print_statuses = False):
         self.parse_units = parse_units
@@ -66,7 +100,7 @@ def __init__(self, source = None, tables = None, parse_units = False, print_stat
             for x in source:
                 self.append(x, tables)
 
-    def drop_duplicates(self, data):
+    def _drop_duplicates(self, data):
         """Drops duplicates from list of dictionaries in place."""
         oset = set()
         drop_indices = []
@@ -81,14 +115,14 @@ def drop_duplicates(self, data):
         for i in reversed(drop_indices):
             del data[i]
 
-    def convert_type(self, data):
+    def _convert_type(self, data):
         """Converts data into appropriate type if it can."""
         try:
             return ast.literal_eval(data)
         except:
             return data
 
-    def clean_unit(self, unit):
+    def _clean_unit(self, unit):
         """Attemps to replace characters and units that astrpoy cannot understand."""
         repl = {
             '-' : ' ',
@@ -113,12 +147,12 @@ def append(self, source, tables = None):
         ----------
         source : str
             A string defining the XML file path.
-        tables: list
+        tables : list, default is None
             A list of strings defining the table names to be loaded from the
             referenced XML file. If None, then all tables in the XML file
             will be parsed.
         """
-        self.print('Parsing:', source)
+        self._print('Parsing:', source)
         messages = set()
         exist_tables = set(self.keys())
         new_tables = set()
@@ -140,15 +174,15 @@ def append(self, source, tables = None):
                         table = elem.attrib['tagname']
                         titledetail = elem.attrib['titledetail']
                         new_tables.add(table)
-                        self.print('Loading:', table)
+                        self._print('Loading:', table)
                         if table not in self.keys():
                             self[table] = []
 
                 elif table is not None and obj is None and elem.tag != 'source_file':
                     obj = elem.tag
                     odict = OrderedDict()
                     if titledetail not in (None, ''):
-                        odict['titledetail'] = self.convert_type(titledetail)
+                        odict['titledetail'] = self._convert_type(titledetail)
 
             elif event == 'end':
                 if elem.tag == 'table':
@@ -161,10 +195,10 @@ def append(self, source, tables = None):
                     obj = None
 
                 elif obj != None:
-                    v = self.convert_type(elem.text)
+                    v = self._convert_type(elem.text)
                     if self.parse_units and type(v) != str and 'units' in elem.attrib:
                         try:
-                            unit = self.clean_unit(elem.attrib['units'])
+                            unit = self._clean_unit(elem.attrib['units'])
                             v *= u.Unit(unit)
                         except:
                             messages.add('Unit {!r} could not be parsed.'.format(elem.attrib['units']))
@@ -175,13 +209,13 @@ def append(self, source, tables = None):
         new_tables &= exist_tables
 
         for key in new_tables:
-            self.print('Dropping Duplicates:', key)
-            self.drop_duplicates(self[key])
+            self._print('Dropping Duplicates:', key)
+            self._drop_duplicates(self[key])
 
         if messages:
             print('\n'.join(messages))
 
-    def print(self, *args):
+    def _print(self, *args):
         """Prints the message if print_statuses is True."""
         if self.print_statuses:
             print(*args)
@@ -204,7 +238,7 @@ def dataframes(self, tables = None):
 
         Parameters
         ----------
-        tables : list
+        tables : list, default is None
             A list of strings defining the table names for which dataframes
             will be created. If None, then all tables parsed in the object
             will be converted.

plsxml/plsxml.py

@@ -10,3 +10,4 @@ codecov>=2.0.15
 jinja2>=2.10
 recommonmark>=0.4.0
 docutils==0.14
+numpydoc>=0.8.0

requirements.txt

@@ -8,7 +8,7 @@ version = 0.0.1
 author = Matt Pewsey
 author_email = [email protected]
 copyright = 2018, Matt Pewsey
-description = Parse PLS-CADD XML files.
+description = Parse PLS-CADD XML files to dictionaries and data frames.
 long_description = file: README.md
 long_description_content_type = text/markdown
 license = BSD 3-Clause License
@@ -17,11 +17,12 @@ url = https://github.com/line-mind/plsxml
 keywords =
   pls-cadd
   xml-parser
-  transmission-line
 classifiers =
-  Programming Language :: Python :: 3
+  Programming Language :: Python :: 3.5
+  Programming Language :: Python :: 3.6
   Operating System :: OS Independent
   License :: OSI Approved :: BSD License
+  Development Status :: 5 - Production/Stable
 
 [options]
 packages = find:
@@ -40,3 +41,4 @@ docs =
   jinja2>=2.10
   recommonmark>=0.4.0
   docutils==0.14
+  numpydoc>=0.8.0