unicode support, major refactor, bootstrap final

- unicode support seems to be working as expected
- graph module now uses same code for class and
  file hierarchies (finally)
    - both versions of hierarchies fully functional
- remaining flake8 errors are future TODO
- ready for upload to pip?

README.rst

@@ -53,12 +53,14 @@ Installation
 
 Exhale is a `Sphinx Extension`__ that depends on `Breathe`_ for access to the Doxygen
 reStructuredText directives, and both `BeautifulSoup`_ and `lxml`_ for parsing the
-generated Doxygen XML documentation.  The easiest way to install Exhale is:
+generated Doxygen XML documentation.  Exhale also uses `six`_ help account for the
+Python 2 unicode dilemma.  The easiest way to install Exhale is:
 
 __ http://www.sphinx-doc.org/en/stable/extensions.html
 
 .. _BeautifulSoup: https://www.crummy.com/software/BeautifulSoup/bs4/doc/
 .. _lxml: http://lxml.de/
+.. _six: http://pythonhosted.org/six/
 
 .. code-block:: bash
 

docs/faq.rst

@@ -29,8 +29,85 @@ Refer to the RTD docs here_.
 
 .. _here: http://docs.readthedocs.io/en/latest/faq.html#my-project-isn-t-building-with-autodoc
 
+Unicode support?
+----------------------------------------------------------------------------------------
+
+Every action Exhale performs with respect to strings is done using unicode strings.  Or
+at least I tried my very best to make sure unicode support works.
+
+1. At the top of every file:
+
+   .. code-block:: py
+
+      from __future__ import unicode_literals
+
+   This is why all of the documentation on this site for strings has a leading ``u``.
+
+2. Every file written to:
+
+   .. code-block:: py
+
+      with codecs.open(file_name, "w", "utf-8") as f:
+
+3. When using Python **3**, ``bytes`` conversion is done as:
+
+   .. code-block:: py
+
+      doxygen_input = bytes(doxygen_input, "utf-8")
+
+The last one may *potentially* cause problems, but in local testing it seems to be OK.
+E.g., if you only specify **ASCII** in your ``conf.py``, everything should work out
+in the end.
+
+.. note::
+
+   Sphinx / reStructuredText supports ``utf-8`` no problem.  The only potential concern
+   is communicating with Doxygen on stdin like this, but it's worked without issue
+   for me so I kept it.  Please speak up if you are experiencing encoding / decoding
+   specific issues in Exhale!
+
+Why does my documentation take so long to build?
+----------------------------------------------------------------------------------------
+
+This is a byproduct of what is actually being done by Exhale.  If you look at the
+build output of Exhale when you execute ``make html``, parsing and generating the
+documents takes on the order of seconds.
+
+What takes long is Sphinx, and the time it takes is directly proportional to the size
+of the API being documented.  The larger the API, the more individual reStructuredText
+documents there are being created.  Meaning there are more documents that Sphinx has
+to read *and* write.
+
+.. note::
+
+   The ``sphinx-bootstrap-theme`` is noticeably slower than others.  I have suspicions
+   as to why, but have not actually investigated potential fixes.
+
+Why are the Sphinx RTD theme "Edit on GitHub" links are invalid?
+----------------------------------------------------------------------------------------
+
+Because I haven't figured out how to implement this correctly yet.  Feel free to give
+input `on the issue`__.  They point to nowhere because you aren't tracking the generated
+API with ``git`` (nor should you be).
+
+__ https://github.com/svenevs/exhale/issues/2
+
+.. tip::
+
+   There is an existing hack you can use to at least make the links go somewhere that
+   exists.  Use the page-level metadata feature of Exhale and point it to the root of
+   your repository:
+
+   .. code-block:: py
+
+      exhale_args = {
+          # ... required / optional arguments ...
+          "pageLevelConfigMeta": ":github_url: https://github.com/you/project"
+      }
+
 Metaprogramming and full template specialization?
 ----------------------------------------------------------------------------------------
+
 Nope.  Partial template specialization at best is supported by Breathe; not full
 template specialization.  Furthermore, Doxygen can barely handle metaprogramming...YMMV.
 

docs/reference_exhale_configs.rst

@@ -238,6 +238,18 @@ theme.  Basically
       your thoughts `on the issue <https://github.com/svenevs/exhale/issues/7>`_,
       explaining which feature you would want to be able to control.
 
+      The currently available customizations :ref:`begin here <bootstrap_mods>`, but it
+      shouldn't be too hard to add more.
+
+   .. tip::
+
+      You will see that many of the color, selection, and search options are **not**
+      available to be customized for ``bootstrap-treeview``.  This is by design.
+      See :data:`exhale.configs.treeViewBootstrapTextSpanClass`,
+      :data:`exhale.configs.treeViewBootstrapIconMimicColor`, and
+      :data:`exhale.configs.treeViewBootstrapOnhoverColor` for your color options.  The
+      links are defined by your bootstrap theme's ``a`` tag color.
+
 See the :ref:`index_credit` section for information on the licensing of these libraries.
 Neither library should produce any legal gray areas for you, but I'm not a lawyer.
 
@@ -249,6 +261,30 @@ Neither library should produce any legal gray areas for you, but I'm not a lawye
 
 .. autodata:: exhale.configs.treeViewIsBootstrap
 
+.. _bootstrap_mods:
+
+.. autodata:: exhale.configs.treeViewBootstrapTextSpanClass
+
+.. autodata:: exhale.configs.treeViewBootstrapIconMimicColor
+
+.. autodata:: exhale.configs.treeViewBootstrapOnhoverColor
+
+.. autodata:: exhale.configs.treeViewBootstrapUseBadgeTags
+
+.. autodata:: exhale.configs.treeViewBootstrapExpandIcon
+
+.. autodata:: exhale.configs.treeViewBootstrapCollapseIcon
+
+.. autodata:: exhale.configs.treeViewBootstrapLevels
+
+.. autodata:: exhale.configs._class_hierarchy_id
+
+.. autodata:: exhale.configs._file_hierarchy_id
+
+.. autodata:: exhale.configs._bstrap_class_hierarchy_fn_data_name
+
+.. autodata:: exhale.configs._bstrap_file_hierarchy_fn_data_name
+
 
 Page Level Customization
 ****************************************************************************************

docs/requirements.txt

@@ -2,3 +2,4 @@ bs4     # BeautifulSoup!
 lxml    # We need the lxml backend for BeautifulSoup.
 sphinx  # Exhale is a Sphinx extension.
 breathe # The directives used for documentation come from the excellent Breathe.
+six     # Primarily for Unicode string types

exhale/__init__.py

@@ -6,6 +6,8 @@
 #                     https://github.com/svenevs/exhale/LICENSE.md                     #
 ########################################################################################
 
+from __future__ import unicode_literals
+
 __version__ = "0.1.0"
 
 
@@ -19,7 +21,6 @@ def environment_ready(app):
     ####### Next, perform any cleanup
 
     # Generate the full API!
-    app.info(utils.info("Exhale: generating reStructuredText documents."))
     try:
         deploy.explode()
     except: