license updates, testing readthedocs.yaml

LICENSE.md

@@ -0,0 +1,29 @@
+3-Clause BSD License
+
+Copyright (c) 2017, Stephen McDowell
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of exhale nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

docs/index.rst

@@ -1,6 +1,12 @@
 Exhale
 ========================================================================================
 
+.. danger::
+
+   These documents are currently largely out of order and most of the documentation you
+   will read pertaining to how it works are out of date.  While you are welcome to
+   use the ``redux`` branch...it's a bad idea at this time.
+
 Automatic C++ library API documentation generation using Doxygen, Sphinx, and Breathe.
 This project attempts to revive the Doxygen style hierarchies in reStructuredText
 documents to enable powerful documentation syntax and generate beautiful websites.
@@ -12,19 +18,42 @@ of automation, enabling launching Doxygen and generating the full website all fr
 ``conf.py``.  Exhale will execute these actions by way of ``sphinx-build`` being invoked,
 allowing you to use it for hosting on `Read the Docs <https://readthedocs.org/>`_.
 
+Getting Started
+----------------------------------------------------------------------------------------
+
 A :ref:`usage_quickstart_guide` guide gives the bare minimum needed to get things
 working, please read the :ref:`overview` section if you are new to documenting code with
 either Doxygen, Sphinx, or Breathe.
 
-This project revives the Doxygen style hierarchies in reStructuredText documents so that
-you can keep using the beautiful Sphinx websites, but have a more human-readable Library
-API without having to manually write it out yourself.  Exhale is self-contained and
-easily portable to Read the Docs.  You should be able to use any Sphinx theme of your
-choosing, though some of them likely work better than others.
+.. tip::
+
+   Exhale might **not** be the tool you are looking for!  It was designed to be as
+   intuitive and flexible as possible, but it does require more machinery to get
+   everything started.
+
+   **Why use it?**
+        The motivation for writing it was to use Sphinx and Doxygen together.  It was
+        largely inspired by Breathe, but I had a strong desire to have the Class and
+        File hierarchies in an **html** format.  Doxygen can generate websites.  Sphinx
+        can generate them better.
+
+    **Why not use it?**
+        It may be more involved than you need.  Check out the ``breathe-apidoc`` tool
+        that comes with your installation of ``breathe``.  It is quite similar to the
+        `Sphinx API doc tool <http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html>`_,
+        and that may be all you are looking for to get your documentation displayed.
 
 A more comprehensive example repository (which was used for testing once upon a time) is
 located at the companion_ site.
 
+.. warning::
+
+   Exhale is undergoing **significant** changes.  It was originally designed as a single
+   file library that was tracked alongside of ``conf.py``.  This was overall more
+   inconvenient and a burden to maintain for users.
+
+   The
+
 .. toctree::
    :maxdepth: 2
 
@@ -41,3 +70,9 @@ Indices and tables
 * :ref:`search`
 
 .. _companion: http://my-favorite-documentation-test.readthedocs.io/en/latest/
+
+Legacy
+========================================================================================
+
+Legacy documentation is `available here <http://exhale.readthedocs.io/en/legacy_docs/>`_
+for if you chanced upon this library when it was a single file.

exhale/__init__.py

@@ -1,32 +1,9 @@
-# This file is part of exhale: https://github.com/svenevs/exhale
-#
-# Copyright (c) 2017, Stephen McDowell
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-#
-# * Redistributions of source code must retain the above copyright notice, this
-#   list of conditions and the following disclaimer.
-#
-# * Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-#
-# * Neither the name of exhale nor the names of its
-#   contributors may be used to endorse or promote products derived from
-#   this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+########################################################################################
+# This file is part of exhale.  Copyright (c) 2017, Stephen McDowell.                  #
+# Full BSD 3-Clause license available here:                                            #
+#                                                                                      #
+#                     https://github.com/svenevs/exhale/LICENSE.md                     #
+########################################################################################
 
 from . import deploy
 from . import utils

exhale/configs.py

@@ -1,32 +1,9 @@
-# This file is part of exhale: https://github.com/svenevs/exhale
-#
-# Copyright (c) 2017, Stephen McDowell
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-#
-# * Redistributions of source code must retain the above copyright notice, this
-#   list of conditions and the following disclaimer.
-#
-# * Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-#
-# * Neither the name of exhale nor the names of its
-#   contributors may be used to endorse or promote products derived from
-#   this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+########################################################################################
+# This file is part of exhale.  Copyright (c) 2017, Stephen McDowell.                  #
+# Full BSD 3-Clause license available here:                                            #
+#                                                                                      #
+#                     https://github.com/svenevs/exhale/LICENSE.md                     #
+########################################################################################
 
 import textwrap
 

exhale/deploy.py

@@ -1,32 +1,10 @@
-# This file is part of exhale: https://github.com/svenevs/exhale
-#
-# Copyright (c) 2017, Stephen McDowell
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-#
-# * Redistributions of source code must retain the above copyright notice, this
-#   list of conditions and the following disclaimer.
-#
-# * Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-#
-# * Neither the name of exhale nor the names of its
-#   contributors may be used to endorse or promote products derived from
-#   this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+########################################################################################
+# This file is part of exhale.  Copyright (c) 2017, Stephen McDowell.                  #
+# Full BSD 3-Clause license available here:                                            #
+#                                                                                      #
+#                     https://github.com/svenevs/exhale/LICENSE.md                     #
+########################################################################################
+
 from . import configs
 from . import utils
 from .graph import ExhaleRoot

exhale/graph.py

@@ -1,32 +1,10 @@
-# This file is part of exhale: https://github.com/svenevs/exhale
-#
-# Copyright (c) 2017, Stephen McDowell
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-#
-# * Redistributions of source code must retain the above copyright notice, this
-#   list of conditions and the following disclaimer.
-#
-# * Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-#
-# * Neither the name of exhale nor the names of its
-#   contributors may be used to endorse or promote products derived from
-#   this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+########################################################################################
+# This file is part of exhale.  Copyright (c) 2017, Stephen McDowell.                  #
+# Full BSD 3-Clause license available here:                                            #
+#                                                                                      #
+#                     https://github.com/svenevs/exhale/LICENSE.md                     #
+########################################################################################
+
 from . import configs
 from . import parse
 from . import utils

exhale/parse.py

@@ -1,32 +1,10 @@
-# This file is part of exhale: https://github.com/svenevs/exhale
-#
-# Copyright (c) 2017, Stephen McDowell
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-#
-# * Redistributions of source code must retain the above copyright notice, this
-#   list of conditions and the following disclaimer.
-#
-# * Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-#
-# * Neither the name of exhale nor the names of its
-#   contributors may be used to endorse or promote products derived from
-#   this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+########################################################################################
+# This file is part of exhale.  Copyright (c) 2017, Stephen McDowell.                  #
+# Full BSD 3-Clause license available here:                                            #
+#                                                                                      #
+#                     https://github.com/svenevs/exhale/LICENSE.md                     #
+########################################################################################
+
 from . import configs
 from .utils import nodeCompoundXMLContents, AnsiColors, exclaimError
 

exhale/utils.py

@@ -1,32 +1,10 @@
-# This file is part of exhale: https://github.com/svenevs/exhale
-#
-# Copyright (c) 2017, Stephen McDowell
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-#
-# * Redistributions of source code must retain the above copyright notice, this
-#   list of conditions and the following disclaimer.
-#
-# * Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-#
-# * Neither the name of exhale nor the names of its
-#   contributors may be used to endorse or promote products derived from
-#   this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+########################################################################################
+# This file is part of exhale.  Copyright (c) 2017, Stephen McDowell.                  #
+# Full BSD 3-Clause license available here:                                            #
+#                                                                                      #
+#                     https://github.com/svenevs/exhale/LICENSE.md                     #
+########################################################################################
+
 from . import configs
 
 import os

readthedocs.yml

@@ -0,0 +1,14 @@
+# See: http://docs.readthedocs.io/en/latest/yaml-config.html
+# Only build html and json
+formats:
+    - none
+
+requirements_file: docs/requirements.txt
+python:
+    version: 3
+    pip_install: true
+# TODO: extra_requirements
+# - bs4
+# - lxml
+# - sphinx
+# - breathe