Merge branch 'feature-auto-docs' into develop

Also fixed some minor mistakes which crept in on the feature branch.

README.md

@@ -109,7 +109,6 @@ or in the [Reference section](docs/README.md) including
 - [Framework build instructions](docs/BUILD.md)
 - [Core build instructions](core/docs/BUILD.md)
 - [Core API Reference](core/docs/API.md)
-- [Python API Reference](core/docs/API_Python.md)
 - [Input File Reference](core/docs/INPUT.md)
 
 There is also a [Wiki](https://iffwiki.fz-juelich.de/index.php/Spirit "Click me..."),
@@ -162,7 +161,7 @@ or simply use
 
     pip install spirit
 
-With this package you have access to powerful [Python APIs](core/docs/API_Python.md) to run and control
+With this package you have access to powerful Python APIs to run and control
 dynamics simulations or optimizations.
 This is especially useful for work on clusters, where you can now script your
 workflow, never having to re-compile when testing, debugging or adding features.

conf.py

@@ -19,6 +19,9 @@
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
+import sys, os
+sys.path.insert( 0, os.path.join( os.path.dirname( __file__ ), "core", "python", "spirit" ) )
+sys.path.insert( 0, os.path.join( os.path.dirname( __file__ ), "core", "python" ) )
 
 
 # At top on conf.py (with other import statements)
@@ -44,7 +47,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx_markdown_tables', 'sphinx.ext.intersphinx',
-    'sphinx.ext.coverage']
+                'sphinx.ext.coverage', 'sphinx.ext.autodoc']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -106,7 +109,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['.github', '_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['.github', '_build', 'pyapidoc/spirit.rst', 'Thumbs.db', '.DS_Store']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -210,3 +213,63 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}
+
+
+
+def run_apidoc(_):
+    """Runs sphinx-apidoc when building the documentation.
+    Needs to be done in conf.py in order to include the APIdoc in the
+    build on readthedocs.
+    See also https://github.com/rtfd/readthedocs.org/issues/1139
+    """
+    source_dir = os.path.abspath(os.path.dirname(__file__))
+    apidoc_dir = os.path.join(source_dir, 'docs', 'pyapidoc')
+    package_dir = os.path.join(source_dir, 'core', 'python', 'spirit')
+
+    import subprocess
+    cmd_path = 'sphinx-apidoc'
+    if hasattr(sys, 'real_prefix'):  # Check to see if we are in a virtualenv
+        # If we are, assemble the path manually
+        cmd_path = os.path.abspath(os.path.join(sys.prefix, 'bin', 'sphinx-apidoc'))
+
+    options = [
+        '-o', apidoc_dir, package_dir,
+        '--force',
+        '--no-headings',
+        '--module-first',
+        '--separate',
+        '--no-toc',
+        '--maxdepth', '4',
+    ]
+
+    builddir = os.path.join(source_dir, 'build')
+    if not os.path.exists(builddir):
+        os.mkdir(builddir)
+    subprocess.check_call(['cmake', '..', '-DSPIRIT_BUILD_FOR_CXX=OFF'], cwd=builddir)
+    subprocess.check_call(['make'], cwd=builddir)
+
+    # See https://stackoverflow.com/a/30144019
+    env = os.environ.copy()
+    env["SPHINX_APIDOC_OPTIONS"] = 'members,special-members,private-members,undoc-members,show-inheritance'
+    subprocess.check_call([cmd_path] + options, env=env)
+
+    #####################
+    with open(os.path.join(apidoc_dir, 'parameters.rst'), "w") as parameters_file:
+        parameters_file.write("Parameters\n==================================\n\n")
+        with open(os.path.join(apidoc_dir, 'spirit.parameters.mc.rst'), 'r') as generated_file:
+            parameters_file.write(generated_file.read())
+        with open(os.path.join(apidoc_dir, 'spirit.parameters.llg.rst'), 'r') as generated_file:
+            parameters_file.write(generated_file.read())
+        with open(os.path.join(apidoc_dir, 'spirit.parameters.gneb.rst'), 'r') as generated_file:
+            parameters_file.write(generated_file.read())
+        with open(os.path.join(apidoc_dir, 'spirit.parameters.ema.rst'), 'r') as generated_file:
+            parameters_file.write(generated_file.read())
+        with open(os.path.join(apidoc_dir, 'spirit.parameters.mmf.rst'), 'r') as generated_file:
+            parameters_file.write(generated_file.read())
+
+
+    if not os.path.exists(apidoc_dir):
+        os.mkdir(apidoc_dir)
+
+def setup(app):
+    app.connect('builder-inited', run_apidoc)

core/CMake/__init__.py.in

@@ -1,3 +1,8 @@
+"""
+Spirit
+==================================================
+"""
+
 __version__ = "${META_VERSION}"
 __revision__ = "${META_VERSION_REVISION}"
 __title__ = "${META_PROJECT_NAME}"