Make docfx great again!

This updates some small outdated pieces with docfx integration:

* Support docfx.json first, if no patterns were explicitly specified
* Refactor output path, use new _api path
* Add missing operator type to .net parsing and template output
* Fix indent issue with code samples
* Add docs on how to actually use docfx + autoapi

Fixes #45
Fixes #46
Fixes #48

README.rst

@@ -48,8 +48,8 @@ Basic Workflow
 Sphinx AutoAPI has the following structure:
 
 * Configure directory to look for source files
-* Generate JSON from those source files, using language-specific tooling
-* Map the JSON into standard AutoAPI Python objects
+* Serialize those source files, using language-specific tooling
+* Map the serialized data into standard AutoAPI Python objects
 * Generate RST through Jinja2 templates from those Python objects
 
 This basic framework should be easy to implement in your language of choice.
@@ -58,38 +58,94 @@ All you need to do is be able to generate a JSON structure that includes your AP
 Install
 -------
 
-
 First you need to install autoapi:
 
 .. code:: bash
-	
-	pip install sphinx-autoapi
+
+    pip install sphinx-autoapi
 
 Then add it to your Sphinx project's ``conf.py``:
 
 .. code:: python
 
-	extensions = ['autoapi.extension']
+    extensions = ['autoapi.extension']
 
-        # Document Python Code
-	autoapi_type = 'python'
-	autoapi_dir = 'path/to/python/files'
+    # Document Python Code
+    autoapi_type = 'python'
+    autoapi_dirs = ['path/to/python/files', 'path/to/more/python/files']
 
-        # Or, Document Go Code
-	autoapi_type = 'go'
-	autoapi_dir = 'path/to/go/files'
+    # Or, Document Go Code
+    autoapi_type = 'go'
+    autoapi_dirs = 'path/to/go/files'
 
-AutoAPI will automatically add itself to the last TOCTree in your top-level ``index.rst``.
+AutoAPI will automatically add itself to the last TOCTree in your top-level
+``index.rst``.
 
-This is needed because we will be outputting rst files into the ``autoapi`` directory.
-This adds it into the global TOCTree for your project,
-so that it appears in the menus.
+This is needed because we will be outputting rst files into the ``autoapi``
+directory.  This adds it into the global TOCTree for your project, so that it
+appears in the menus.
 
-We hope to be able to dynamically add items into the TOCTree, and remove this step.
-However, it is currently required.
+We hope to be able to dynamically add items into the TOCTree, and remove this
+step.  However, it is currently required.
 
 See all available configuration options in :doc:`config`.
 
+Setup
+-----
+
+.NET
+~~~~
+
+The .NET mapping utilizes the tool `docfx`_. To install ``docfx``, first
+you'll need to `install a .NET runtime on your system <ASP.NET Installation>`_.
+
+The docfx tool can be installed with::
+
+    dnu commands install docfx
+
+By default, ``docfx`` will output metadata files into the ``_api`` path. You
+can configure which path to output files into using a ``docfx.json`` file in
+your project's repository. Here's an example from the ASP.NET docs:
+
+.. code:: json
+
+    {
+      "metadata": [{
+        "src": [{
+          "files": [
+            "aspnet/identity/src/\*\*/project.json"
+          ],
+          "exclude": [
+            "aspnet/testing/src/Microsoft.AspNet.Testing/\*"
+          ]
+        }],
+        "dest": "docs/_api",
+        "force": "true",
+        "raw": "true"
+      }]
+    }
+
+.. note::
+    The ``dest`` configuration option is required to output to the ``docs/``
+    path, where autoapi knows to search for these files.
+
+With a working ``docfx`` toolchain, you can now add the configuration options
+to enable the .NET autoapi mapper. In your ``conf.py``:
+
+.. code:: python
+
+    extensions = ['autoapi.extension']
+    autoapi_type = 'dotnet'
+    autoapi_dirs = ['..']
+
+This configuration, which assumes your ``conf.py`` is in a ``docs/`` path,
+will use your parent path to search for files to pass to ``docfx``. If you
+have a ``docfx.json`` file present, and did not specify a custom pattern for
+finding files, ``docfx.json`` will be used first.
+
+.. _`docfx`: https://github.com/dotnet/docfx
+.. _`ASP.NET Installation`: http://docs.asp.net/en/latest/getting-started/index.html
+
 Customize
 ---------
 
@@ -106,7 +162,7 @@ Currently Implemented
 ---------------------
 
 * Python (2 only -- Epydoc doesn't support Python 3)
-* .Net
+* .NET
 * Go
 * Javascript
 

autoapi/mappers/dotnet.py

@@ -49,23 +49,35 @@ class DotNetSphinxMapper(SphinxMapperBase):
     '''Auto API domain handler for .NET
 
     Searches for YAML files, and soon to be JSON files as well, for auto API
-    sources
+    sources. If not pattern configuration was explicitly specified, then default
+    to looking up a ``docfx.json`` file.
 
     :param app: Sphinx application passed in as part of the extension
     '''
 
     top_namespaces = {}
 
+    DOCFX_OUTPUT_PATH = '_api'
+
     def load(self, patterns, dirs, ignore=None, **kwargs):
-        '''
-        Load objects from the filesystem into the ``paths`` dictionary.
+        '''Load objects from the filesystem into the ``paths`` dictionary.
 
+        If a patterns setting was not specified, look for a ``docfx.json`` file
+        by default.  A ``docfx.json`` should be treated as the canonical source
+        before the default patterns.  Fallback to default pattern matches if no
+        ``docfx.json`` files are found.
         '''
         raise_error = kwargs.get('raise_error', True)
         all_files = set()
-        for _file in self.find_files(patterns=patterns, dirs=dirs, ignore=ignore):
-            # Iterating for Sphinx output clarify
-            all_files.add(_file)
+        if not self.app.config.autoapi_file_patterns:
+            all_files = set()
+            for _file in self.find_files(patterns=['docfx.json'], dirs=dirs,
+                                         ignore=ignore):
+                all_files.add(_file)
+        if not all_files:
+            for _file in self.find_files(patterns=patterns, dirs=dirs,
+                                         ignore=ignore):
+                all_files.add(_file)
         if all_files:
             try:
                 command = ['docfx', 'metadata', '--raw', '--force']
@@ -88,7 +100,9 @@ class DotNetSphinxMapper(SphinxMapperBase):
                 if raise_error:
                     raise ExtensionError('Failure in docfx while generating AutoAPI output.')
         # We now have yaml files
-        for xdoc_path in self.find_files(patterns=['*.yml'], dirs=['_api_'], ignore=ignore):
+        for xdoc_path in self.find_files(patterns=['*.yml'],
+                                         dirs=[self.DOCFX_OUTPUT_PATH],
+                                         ignore=ignore):
             data = self.read_file(path=xdoc_path)
             if data:
                 self.paths[xdoc_path] = data
@@ -231,8 +245,8 @@ class DotNetSphinxMapper(SphinxMapperBase):
     def build_finished(app, exception):
         if app.verbosity > 1:
             app.info(bold('[AutoAPI] ') + darkgreen('Cleaning generated .yml files'))
-        if os.path.exists('_api_'):
-            shutil.rmtree('_api_')
+        if os.path.exists(DotNetSphinxMapper.DOCFX_OUTPUT_PATH):
+            shutil.rmtree(DotNetSphinxMapper.DOCFX_OUTPUT_PATH)
 
 
 class DotNetPythonMapper(PythonMapperBase):
@@ -487,6 +501,12 @@ class DotNetMethod(DotNetPythonMapper):
     plural = 'methods'
 
 
+class DotNetOperator(DotNetPythonMapper):
+    type = 'operator'
+    ref_directive = 'op'
+    plural = 'operators'
+
+
 class DotNetProperty(DotNetPythonMapper):
     type = 'property'
     ref_directive = 'prop'
@@ -548,6 +568,6 @@ class DotNetEvent(DotNetPythonMapper):
 
 ALL_CLASSES = [
     DotNetNamespace, DotNetClass, DotNetEnum, DotNetStruct,
-    DotNetInterface, DotNetDelegate, DotNetProperty, DotNetMethod,
-    DotNetConstructor, DotNetField, DotNetEvent
+    DotNetInterface, DotNetDelegate, DotNetOperator, DotNetProperty,
+    DotNetMethod, DotNetConstructor, DotNetField, DotNetEvent
 ]

autoapi/templates/dotnet/operator.rst

@@ -0,0 +1 @@
+{% extends "dotnet/base_embed.rst" %}

tests/test_domains.py

@@ -12,8 +12,12 @@ class DotNetSphinxMapperTests(unittest.TestCase):
     def setUp(self):
         '''Test setup'''
         class _config(object):
-            autoapi_dirs = ['/tmp/autoapi/tmp']
-            autoapi_root = '/tmp/autoapi/root'
+            def __getattr__(self, key):
+                attrs = {
+                    'autoapi_dirs': ['/tmp/autoapi/tmp'],
+                    'autoapi_root': '/tmp/autoapi/root',
+                }
+                return attrs.get(key, None)
 
         class _application(object):
             config = _config()