Refactor hierarchy

.gitignore

@@ -14,9 +14,12 @@
 
 mphys.egg-info/*
 docs/build/doctrees
+docs/_build
 *__pycache__
 build/
 dist/
 
 # input files
-tests/input_files/*.xyz
+tests/input_files/*.xyz
+
+.ropeproject

.vscode/settings.json

@@ -0,0 +1,9 @@
+{
+    "restructuredtext.confPath": "${workspaceFolder}/docs",
+    "python.formatting.provider": "autopep8",
+    "python.formatting.autopep8Args": [
+        "--max-line-length",
+        "100",
+        "--experimental"
+    ]
+}

README.md

@@ -12,12 +12,16 @@ or for a development version
 pip install -e .
 ```
 
+## Building the Docs
+The documentation includes N2 diagrams from the unit tests. Before building the docs, go into `tests/unit_tests` and run `python -m unittest`.
+Then go into the `docs` directory and run `make html`.
 
 
 ## Tests
 The test are written to use the testflo framework because it allows us to run tests with multiple cores.
 To run the tests you will need.
 
+### Integration Tests
 These python packages
 ```
 adflow

docs/Makefile

@@ -5,8 +5,8 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
+SOURCEDIR     = .
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:

docs/_exts/embed_bibtex.py

@@ -0,0 +1,76 @@
+
+import sys
+import importlib
+
+from docutils import nodes
+
+import sphinx
+from docutils.parsers.rst import Directive
+
+from sphinx.writers.html import HTMLTranslator
+from sphinx.writers.html5 import HTML5Translator
+from sphinx.errors import SphinxError
+
+
+class bibtex_node(nodes.Element):
+    pass
+
+
+def visit_bibtex_node(self, node):
+    pass
+
+
+def depart_bibtex_node(self, node):
+    """
+    This function creates the formatting that sets up the look of the blocks.
+    The look of the formatting is controlled by _theme/static/style.css
+    """
+    if not isinstance(self, (HTMLTranslator, HTML5Translator)):
+        self.body.append("output only available for HTML\n")
+        return
+
+    html = """
+    <div class="cell border-box-sizing code_cell rendered">
+       <div class="output_area"><pre>{}</pre></div>
+    </div>""".format(node["text"])
+
+    self.body.append(html)
+
+
+class EmbedBibtexDirective(Directive):
+    """
+    EmbedBibtexDirective is a custom directive to allow a Bibtex citation to be embedded.
+
+    .. embed-bibtex::
+        openmdao.solvers.linear.petsc_ksp
+        PETScKrylov
+
+
+    The 2 arguments are the module path and the class name.
+
+    What the above will do is replace the directive and its args with the Bibtex citation
+    for the class.
+
+    """
+
+    required_arguments = 2
+    optional_arguments = 0
+    has_content = True
+
+    def run(self):
+        module_path, class_name = self.arguments
+        mod = importlib.import_module(module_path)
+        obj = getattr(mod, class_name)()
+
+        if not hasattr(obj, 'cite') or not obj.cite:
+            raise SphinxError("Couldn't find 'cite' in class '%s'" % class_name)
+
+        return [bibtex_node(text=obj.cite)]
+
+
+def setup(app):
+    """add custom directive into Sphinx so that it is found during document parsing"""
+    app.add_directive('embed-bibtex', EmbedBibtexDirective)
+    app.add_node(bibtex_node, html=(visit_bibtex_node, depart_bibtex_node))
+
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}