Archives/sphinx-autoapi
2
0
Fork 0
mirror of https://github.com/readthedocs/sphinx-autoapi synced 2024-11-02 15:40:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #9 from rtfd/plane-work

Browse Source 
Refactor domains to mappers/etc, improve abstractions for handling per-language constructs
This commit is contained in:
Anthony 2015-06-22 10:48:30 -07:00
commit ff47ed4603
38 changed files with 2143 additions and 356 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
.gitignore vendored
View File

@ -1,6 +1,10 @@
*.pyc
_build
_build_rtd
readthedocs_build
docs/autoapi
*.egg-info
*.pyc
*.swp
.doctrees
_build_rtd
docs/_build
docs/autoapi
readthedocs_build
tests/*/_build
tests/*/autoapi

18
README.rst
View File

@ -114,9 +114,17 @@ Currently Implemented
* Go
* Javascript
Future
------
Adding a new language
---------------------
Adding a new language should only take a couple of hours,
assuming your language has a tool to generate JSON from API documentation.
The steps to follow:
* Add a new Mapper file in `mappers/`. It's probably easiest to copy an existing one, like the Javascript or Python mappers.
* Implement the :py:func:`create_class` and :py:func:`read_file` methods on the :py:class:`SphinxMapperBase`.
* Implement all appropriate object types on the :py:class:`PythonMapperBase`
* Add a test in the `tests/test_integration.py`, along with an example project for the testing.
* Include it in the class mapping in `mappers/base.py` and `extension.py`
Our goal is to support all languages.
Implementation is quite simple,
we'll be adding more docs on implementation soon.

3
autoapi/__init__.py
View File

@ -0,0 +1,3 @@
"""
AutoAPI Top-level Comment
"""

4
autoapi/domains/__init__.py
View File

@ -1,4 +0,0 @@
from .dotnet import DotNetDomain
from .python import PythonDomain
from .go import GoDomain
from .javascript import JavaScriptDomain

44
autoapi/extension.py
View File

@ -1,13 +1,19 @@
# -*- coding: utf-8 -*-
"""
Sphinx Auto-API
Sphinx Auto-API Top-level Extension.
This extension allows you to automagically generate API documentation from your project.
"""
import os
import fnmatch
import shutil
from .domains import DotNetDomain, PythonDomain, GoDomain, JavaScriptDomain
from sphinx.util.console import darkgreen, bold
from .mappers import DotNetSphinxMapper, PythonSphinxMapper, GoSphinxMapper, JavaScriptSphinxMapper
default_options = ['members', 'undoc-members', 'private-members', 'special-members']
def ignore_file(app, filename):
@ -17,7 +23,7 @@ def ignore_file(app, filename):
return False
def load_yaml(app):
def run_autoapi(app):
"""
Load AutoAPI data from the filesystem.
"""
@ -25,47 +31,53 @@ def load_yaml(app):
if not app.config.autoapi_dir:
print "You must configure an autodapi_dir setting."
return
app.env.autoapi_data = []
mapping = {
'python': PythonDomain,
'dotnet': DotNetDomain,
'go': GoDomain,
'javascript': JavaScriptDomain,
'python': PythonSphinxMapper,
'dotnet': DotNetSphinxMapper,
'go': GoSphinxMapper,
'javascript': JavaScriptSphinxMapper,
}
domain = mapping[app.config.autoapi_type]
domain_obj = domain(app)
app.info('[AutoAPI] Loading Data')
domain_obj = domain(app, template_dir=app.config.autoapi_template_dir)
app.info(bold('[AutoAPI] ') + darkgreen('Loading Data'))
domain_obj.load(
pattern=app.config.autoapi_file_pattern,
dir=os.path.normpath(app.config.autoapi_dir),
ignore=app.config.autoapi_ignore,
)
app.info('[AutoAPI] Mapping Data')
domain_obj.map()
app.info('[AutoAPI] Rendering Data')
app.info(bold('[AutoAPI] ') + darkgreen('Mapping Data'))
domain_obj.map(options=app.config.autoapi_options)
app.info(bold('[AutoAPI] ') + darkgreen('Rendering Data'))
domain_obj.output_rst(
root=app.config.autoapi_root,
# TODO: Better way to determine suffix?
source_suffix=app.config.source_suffix[0]
source_suffix=app.config.source_suffix[0],
)
def build_finished(app, exception):
if not app.config.autoapi_keep_files:
if app.verbosity > 1:
print "Cleaning autoapi out"
app.info(bold('[AutoAPI] ') + darkgreen('Cleaning generated .rst files'))
shutil.rmtree(app.config.autoapi_root)
def setup(app):
app.connect('builder-inited', load_yaml)
app.connect('builder-inited', run_autoapi)
app.connect('build-finished', build_finished)
app.add_config_value('autoapi_type', 'python', 'html')
app.add_config_value('autoapi_root', 'autoapi', 'html')
app.add_config_value('autoapi_ignore', ['*migrations*'], 'html')
app.add_config_value('autoapi_options', default_options, 'html')
app.add_config_value('autoapi_file_pattern', '*', 'html')
app.add_config_value('autoapi_dir', '', 'html')
app.add_config_value('autoapi_keep_files', True, 'html')
app.add_config_value('autoapi_keep_files', False, 'html')
app.add_config_value('autoapi_template_dir', [], 'html')
app.add_stylesheet('autoapi.css')

4
autoapi/mappers/__init__.py Normal file
View File

@ -0,0 +1,4 @@
from .dotnet import DotNetSphinxMapper
from .python import PythonSphinxMapper
from .go import GoSphinxMapper
from .javascript import JavaScriptSphinxMapper

107
autoapi/domains/base.py → autoapi/mappers/base.py
View File

@ -1,7 +1,6 @@
import os
import yaml
import json
import fnmatch
from collections import OrderedDict
from jinja2 import Environment, FileSystemLoader, TemplateNotFound
from sphinx.util.console import darkgreen
@ -11,17 +10,48 @@ from sphinx.util.osutil import ensuredir
from ..settings import TEMPLATE_DIR
class AutoAPIBase(object):
class PythonMapperBase(object):
'''
Base object for JSON -> Python object mapping.
Subclasses of this object will handle their language specific JSON input,
and map that onto this standard Python object.
Subclasses may also include language-specific attributes on this object.
Arguments:
:param obj: JSON object representing this object
:param jinja_env: A template environment for rendering this object
Required attributes:
:var str id: A globally unique indentifier for this object. Generally a fully qualified name, including namespace.
:var str name: A short "display friendly" name for this object.
Optional attributes:
:var str docstring: The documentation for this object
:var list imports: Imports in this object
:var list children: Children of this object
:var list parameters: Parameters to this object
:var list methods: Methods on this object
'''
language = 'base'
type = 'base'
# Create a page in the output for this object.
top_level_object = False
def __init__(self, obj):
def __init__(self, obj, options=None, jinja_env=None):
self.obj = obj
self.options = options
if jinja_env:
self.jinja_env = jinja_env
def render(self, ctx=None):
if not ctx:
ctx = {}
def render(self, **kwargs):
ctx = {}
try:
template = self.jinja_env.get_template(
'{language}/{type}.rst'.format(language=self.language, type=self.type)
@ -33,8 +63,14 @@ class AutoAPIBase(object):
)
ctx.update(**self.get_context_data())
ctx.update(**kwargs)
return template.render(**ctx)
@property
def rendered(self):
'Shortcut to render an object in templates.'
return self.render()
def get_absolute_path(self):
return "/autoapi/{type}/{name}".format(
type=self.type,
@ -48,9 +84,9 @@ class AutoAPIBase(object):
def __lt__(self, other):
'''Object sorting comparison'''
if isinstance(other, AutoAPIBase):
if isinstance(other, PythonMapperBase):
return self.id < other.id
return super(AutoAPIBase, self).__lt__(other)
return super(PythonMapperBase, self).__lt__(other)
def __str__(self):
return '<{cls} {id}>'.format(cls=self.__class__.__name__,
@ -76,29 +112,31 @@ class AutoAPIBase(object):
return '.'.join(pieces)
class AutoAPIDomain(object):
class SphinxMapperBase(object):
'''Base class for domain handling
'''Base class for mapping `PythonMapperBase` objects to Sphinx.
:param app: Sphinx application instance
'''
# Mapping of {filepath -> raw data}
paths = {}
paths = OrderedDict()
# Mapping of {object id -> Python Object}
objects = {}
objects = OrderedDict()
# Mapping of {namespace id -> Python Object}
namespaces = OrderedDict()
# Mapping of {namespace id -> Python Object}
top_level_objects = OrderedDict()
namespaces = {}
top_level_objects = {}
def __init__(self, app):
def __init__(self, app, template_dir=None):
self.app = app
TEMPLATE_PATHS = [TEMPLATE_DIR]
USER_TEMPLATE_DIR = self.get_config('autoapi_template_dir')
if USER_TEMPLATE_DIR:
if template_dir:
# Put at the front so it's loaded first
TEMPLATE_PATHS.insert(0, USER_TEMPLATE_DIR)
TEMPLATE_PATHS.insert(0, template_dir)
self.jinja_env = Environment(
loader=FileSystemLoader(TEMPLATE_PATHS)
@ -138,7 +176,7 @@ class AutoAPIDomain(object):
len(files_to_read)):
yield _path
def read_file(self, path, format='yaml'):
def read_file(self, path, **kwargs):
'''Read file input into memory
:param path: Path of file to read
@ -155,17 +193,13 @@ class AutoAPIDomain(object):
'''
self.objects[obj.id] = obj
def get_config(self, key, default=None):
if self.app.config is not None:
return getattr(self.app.config, key, default)
def map(self):
def map(self, options=None):
'''Trigger find of serialized sources and build objects'''
for path, data in self.paths.items():
for obj in self.create_class(data):
for obj in self.create_class(data, options=options):
self.add_object(obj)
def create_class(self, obj):
def create_class(self, obj, options=None):
'''
Create class object.
@ -176,14 +210,19 @@ class AutoAPIDomain(object):
def output_rst(self, root, source_suffix):
for id, obj in self.objects.items():
if not obj:
if not obj or not obj.top_level_object:
continue
rst = obj.render()
if not rst:
continue
detail_dir = os.path.join(root, *id.split('.'))
try:
filename = id.split('(')[0]
except IndexError:
filename = id
filename = filename.replace('#', '-')
detail_dir = os.path.join(root, *filename.split('.'))
ensuredir(detail_dir)
path = os.path.join(detail_dir, '%s%s' % ('index', source_suffix))
with open(path, 'w+') as detail_file:
@ -191,6 +230,12 @@ class AutoAPIDomain(object):
# Render Top Index
top_level_index = os.path.join(root, 'index.rst')
pages = self.objects.values()
# for key, item in self.objects.items():
# if key.count('.') == 1:
# top_level_pages.append(item)
# else:
# print key, key.find('.')
with open(top_level_index, 'w+') as top_level_file:
content = self.jinja_env.get_template('index.rst')
top_level_file.write(content.render())
top_level_file.write(content.render(pages=pages))

178
autoapi/domains/dotnet.py → autoapi/mappers/dotnet.py
View File

@ -1,14 +1,12 @@
import os
from collections import defaultdict
import yaml
from sphinx.util.osutil import ensuredir
from .base import AutoAPIBase, AutoAPIDomain
from .base import PythonMapperBase, SphinxMapperBase
MADE = set()
class DotNetDomain(AutoAPIDomain):
class DotNetSphinxMapper(SphinxMapperBase):
'''Auto API domain handler for .NET
@ -20,8 +18,37 @@ class DotNetDomain(AutoAPIDomain):
top_namespaces = {}
def create_class(self, data):
'''Return instance of class based on Roslyn type property
def read_file(self, path, **kwargs):
'''Read file input into memory, returning deserialized objects
:param path: Path of file to read
'''
# TODO support JSON here
# TODO sphinx way of reporting errors in logs?
try:
with open(path, 'r') as handle:
parsed_data = yaml.safe_load(handle)
return parsed_data
except IOError:
self.app.warn('Error reading file: {0}'.format(path))
except TypeError:
self.app.warn('Error reading file: {0}'.format(path))
return None
# Subclassed to iterate over items
def map(self, options=None, **kwargs):
'''Trigger find of serialized sources and build objects'''
for path, data in self.paths.items():
for item in data['items']:
for obj in self.create_class(item, options):
self.add_object(obj)
self.organize_objects()
def create_class(self, data, options=None, **kwargs):
'''
Return instance of class based on Roslyn type property
Data keys handled here:
@ -34,24 +61,17 @@ class DotNetDomain(AutoAPIDomain):
:param data: dictionary data from Roslyn output artifact
'''
obj_map = dict(
(cls.type, cls) for cls
in [
DotNetNamespace, DotNetClass, DotNetEnum, DotNetStruct,
DotNetInterface, DotNetDelegate, DotNetProperty, DotNetMethod,
DotNetConstructor, DotNetField, DotNetEvent
])
in ALL_CLASSES
)
try:
cls = obj_map[data['type'].lower()]
except KeyError:
self.app.warn('Unknown type: %s' % data)
else:
obj = cls(data)
# TODO what is MADE?
if data.get('id', None) in MADE:
self.app.warn("Object already added: %s" % data.get('id'))
MADE.add(data['id'])
obj = cls(data, jinja_env=self.jinja_env, options=options)
# Append child objects
# TODO this should recurse in the case we're getting back more
@ -63,20 +83,6 @@ class DotNetDomain(AutoAPIDomain):
yield obj
def get_objects(self, pattern):
'''Trigger find of serialized sources and build objects'''
for path in self.find_files(pattern):
data_objects = self.read_file(path)
if type(data_objects) == dict:
data_objects = data_objects['items']
try:
for data in data_objects:
for obj in self.create_class(data):
self.add_object(obj)
except:
import traceback
traceback.print_exc()
def add_object(self, obj):
'''Add object to local and app environment storage
@ -127,63 +133,44 @@ class DotNetDomain(AutoAPIDomain):
if len(ns.children) == 0:
del self.namespaces[key]
def full(self):
print "Reading"
self.get_objects(self.get_config('autoapi_file_pattern'))
self.organize_objects()
# def output_rst(self, root, source_suffix):
# for obj in self.top_level_objects.values():
print "Writing"
self.generate_output()
self.write_indexes()
# if not obj:
# continue
def generate_output(self):
for obj in self.top_level_objects.values():
# rst = obj.render()
# if not rst:
# continue
if not obj:
continue
# # Detail
# try:
# filename = obj.name.split('(')[0]
# except IndexError:
# filename = obj.name
# detail_dir = os.path.join(root, *filename.split('.'))
# ensuredir(detail_dir)
# # TODO: Better way to determine suffix?
# path = os.path.join(detail_dir, '%s%s' % ('index', source_suffix))
# with open(path, 'w+') as detail_file:
# detail_file.write(rst.encode('utf-8'))
# # Write Indexes
# top_level_index = os.path.join(root, 'index.rst')
# with open(top_level_index, 'w+') as top_level_file:
# content = self.jinja_env.get_template('index.rst')
# top_level_file.write(content.render(pages=self.namespaces.values()))
rst = obj.render()
# Detail
try:
filename = obj.name.split('(')[0]
except IndexError:
filename = obj.name
detail_dir = os.path.join(self.get_config('autoapi_root'),
*filename.split('.'))
ensuredir(detail_dir)
# TODO: Better way to determine suffix?
path = os.path.join(detail_dir, '%s%s' % ('index', self.get_config('source_suffix')[0]))
if rst:
with open(path, 'w+') as detail_file:
detail_file.write(rst.encode('utf-8'))
# for namespace, obj in self.namespaces.items():
# path = os.path.join(self.get_config('autoapi_root'), '%s%s' % (namespace, self.get_config('source_suffix')[0]))
# ensuredir(self.get_config('autoapi_root'))
# with open(path, 'w+') as index_file:
# namespace_rst = obj.render()
# if namespace_rst:
# index_file.write(namespace_rst)
def write_indexes(self):
# Write Index
top_level_index = os.path.join(self.get_config('autoapi_root'),
'index.rst')
with open(top_level_index, 'w+') as top_level_file:
content = self.jinja_env.get_template('index.rst')
top_level_file.write(content.render(pages=self.namespaces.values()))
class DotNetBase(AutoAPIBase):
class DotNetPythonMapper(PythonMapperBase):
'''Base .NET object representation'''
language = 'dotnet'
top_level_object = False
def __init__(self, obj):
super(DotNetBase, self).__init__(obj)
def __init__(self, obj, **kwargs):
super(DotNetPythonMapper, self).__init__(obj, **kwargs)
# Always exist
self.id = obj['id']
@ -252,9 +239,10 @@ class DotNetBase(AutoAPIBase):
return '{repo}/blob/master/{path}'.format(
repo=repo,
path=path,
)
)
except:
import traceback; traceback.print_exc();
import traceback
traceback.print_exc()
return ''
@property
@ -309,26 +297,26 @@ class DotNetBase(AutoAPIBase):
return self.ref_name.split('.')[-1]
class DotNetNamespace(DotNetBase):
class DotNetNamespace(DotNetPythonMapper):
type = 'namespace'
ref_directive = 'ns'
plural = 'namespaces'
top_level_object = True
class DotNetMethod(DotNetBase):
class DotNetMethod(DotNetPythonMapper):
type = 'method'
ref_directive = 'meth'
plural = 'methods'
class DotNetProperty(DotNetBase):
class DotNetProperty(DotNetPythonMapper):
type = 'property'
ref_directive = 'prop'
plural = 'properties'
class DotNetEnum(DotNetBase):
class DotNetEnum(DotNetPythonMapper):
type = 'enum'
ref_type = 'enumeration'
ref_directive = 'enum'
@ -336,7 +324,7 @@ class DotNetEnum(DotNetBase):
top_level_object = True
class DotNetStruct(DotNetBase):
class DotNetStruct(DotNetPythonMapper):
type = 'struct'
ref_type = 'structure'
ref_directive = 'struct'
@ -344,38 +332,44 @@ class DotNetStruct(DotNetBase):
top_level_object = True
class DotNetConstructor(DotNetBase):
class DotNetConstructor(DotNetPythonMapper):
type = 'constructor'
ref_directive = 'ctor'
plural = 'constructors'
class DotNetInterface(DotNetBase):
class DotNetInterface(DotNetPythonMapper):
type = 'interface'
ref_directive = 'iface'
plural = 'interfaces'
top_level_object = True
class DotNetDelegate(DotNetBase):
class DotNetDelegate(DotNetPythonMapper):
type = 'delegate'
ref_directive = 'del'
plural = 'delegates'
top_level_object = True
class DotNetClass(DotNetBase):
class DotNetClass(DotNetPythonMapper):
type = 'class'
ref_directive = 'cls'
plural = 'classes'
top_level_object = True
class DotNetField(DotNetBase):
class DotNetField(DotNetPythonMapper):
type = 'field'
plural = 'fields'
class DotNetEvent(DotNetBase):
class DotNetEvent(DotNetPythonMapper):
type = 'event'
plural = 'events'
ALL_CLASSES = [
DotNetNamespace, DotNetClass, DotNetEnum, DotNetStruct,
DotNetInterface, DotNetDelegate, DotNetProperty, DotNetMethod,
DotNetConstructor, DotNetField, DotNetEvent
]

110
autoapi/domains/go.py → autoapi/mappers/go.py
View File

@ -1,11 +1,10 @@
import os
import json
import subprocess
from sphinx.util.osutil import ensuredir
from .base import AutoAPIBase, AutoAPIDomain
from .base import PythonMapperBase, SphinxMapperBase
class GoDomain(AutoAPIDomain):
class GoSphinxMapper(SphinxMapperBase):
'''Auto API domain handler for Go
@ -14,30 +13,38 @@ class GoDomain(AutoAPIDomain):
:param app: Sphinx application passed in as part of the extension
'''
# def read_file(self, path, format=None):
# '''Read file input into memory, returning deserialized objects
def load(self, pattern, dir, ignore=[]):
'''
Load objects from the filesystem into the ``paths`` dictionary.
# :param path: Path of file to read
# '''
# TODO support JSON here
# TODO sphinx way of reporting errors in logs?
'''
data = self.read_file(dir)
if data:
self.paths[dir] = data
# try:
# raw_json = os.system('godocjson %s' % path)
# parsed_data = json.loads(raw_json)
# return parsed_data
# except IOError:
# print Warning('Error reading file: {0}'.format(path))
# except TypeError:
# print Warning('Error reading file: {0}'.format(path))
# return None
def read_file(self, path, **kwargs):
'''Read file input into memory, returning deserialized objects
def create_class(self, data):
:param path: Path of file to read
'''
# TODO support JSON here
# TODO sphinx way of reporting errors in logs?
try:
parsed_data = json.loads(subprocess.check_output(['godocjson', path]))
return parsed_data
except IOError:
self.app.warn('Error reading file: {0}'.format(path))
except TypeError:
self.app.warn('Error reading file: {0}'.format(path))
return None
def create_class(self, data, options=None, _type=None):
'''Return instance of class based on Go data
Data keys handled here:
type
_type
Set the object class
consts, types, vars, funcs
@ -51,7 +58,12 @@ class GoDomain(AutoAPIDomain):
in ALL_CLASSES
)
try:
cls = obj_map[data['type']]
# Contextual type data from children recursion
if _type:
self.app.debug('Forcing Go Type %s' % _type)
cls = obj_map[_type]
else:
cls = obj_map[data['type']]
except KeyError:
self.app.warn('Unknown Type: %s' % data)
else:
@ -67,46 +79,23 @@ class GoDomain(AutoAPIDomain):
yield obj
else:
# Recurse for children
obj = cls(data, env=self.jinja_env)
obj = cls(data, jinja_env=self.jinja_env)
for child_type in ['consts', 'types', 'vars', 'funcs']:
for child_data in data.get(child_type, []):
obj.children += list(self.create_class(child_data))
obj.children += list(self.create_class(
child_data,
_type=child_type.replace('consts', 'const').replace('types', 'type').replace('vars', 'variable').replace('funcs', 'func')
))
yield obj
def full(self):
self.get_objects(self.get_config('autoapi_file_pattern'), format='json')
self.generate_output()
self.write_indexes()
def generate_output(self):
for obj in self.app.env.autoapi_data:
if not obj:
continue
rst = obj.render()
# Detail
try:
filename = obj.name.split('(')[0]
except IndexError:
filename = obj.name
detail_dir = os.path.join(self.get_config('autoapi_root'),
*filename.split('.'))
ensuredir(detail_dir)
# TODO: Better way to determine suffix?
path = os.path.join(detail_dir, '%s%s' % ('index', self.get_config('source_suffix')[0]))
if rst:
with open(path, 'w+') as detail_file:
detail_file.write(rst.encode('utf-8'))
class GoBase(AutoAPIBase):
class GoPythonMapper(PythonMapperBase):
language = 'go'
inverted_names = False
def __init__(self, obj):
super(GoBase, self).__init__(obj)
def __init__(self, obj, **kwargs):
super(GoPythonMapper, self).__init__(obj, **kwargs)
self.name = obj.get('name') or obj.get('packageName')
self.id = self.name
@ -153,32 +142,33 @@ class GoBase(AutoAPIBase):
return self.obj.get('methods', [])
class GoVariable(GoBase):
class GoVariable(GoPythonMapper):
type = 'var'
inverted_names = True
class GoMethod(GoBase):
class GoMethod(GoPythonMapper):
type = 'method'
ref_directive = 'meth'
class GoConstant(GoBase):
class GoConstant(GoPythonMapper):
type = 'const'
inverted_names = True
class GoFunction(GoBase):
class GoFunction(GoPythonMapper):
type = 'func'
ref_type = 'function'
class GoPackage(GoBase):
class GoPackage(GoPythonMapper):
type = 'package'
ref_directive = 'pkg'
top_level_object = True
class GoType(GoBase):
class GoType(GoPythonMapper):
type = 'type'

37
autoapi/domains/javascript.py → autoapi/mappers/javascript.py
View File

@ -1,12 +1,11 @@
import os
import json
import subprocess
from .base import AutoAPIBase, AutoAPIDomain
from .base import PythonMapperBase, SphinxMapperBase
class JavaScriptDomain(AutoAPIDomain):
class JavaScriptSphinxMapper(SphinxMapperBase):
'''Auto API domain handler for Javascript
@ -27,20 +26,21 @@ class JavaScriptDomain(AutoAPIDomain):
parsed_data = json.loads(subprocess.check_output(['jsdoc', '-X', path]))
return parsed_data
except IOError:
print Warning('Error reading file: {0}'.format(path))
self.app.warn('Error reading file: {0}'.format(path))
except TypeError:
print Warning('Error reading file: {0}'.format(path))
self.app.warn('Error reading file: {0}'.format(path))
return None
def map(self):
# Subclassed to iterate over items
def map(self, options=None, **kwargs):
'''Trigger find of serialized sources and build objects'''
for path, data in self.paths.items():
for item in data:
for obj in self.create_class(item):
for obj in self.create_class(item, options):
obj.jinja_env = self.jinja_env
self.add_object(obj)
def create_class(self, data):
def create_class(self, data, options=None, **kwargs):
'''Return instance of class based on Javascript data
Data keys handled here:
@ -64,19 +64,19 @@ class JavaScriptDomain(AutoAPIDomain):
self.app.warn('Unknown Type: %s' % data)
else:
# Recurse for children
obj = cls(data)
obj = cls(data, jinja_env=self.jinja_env)
if 'children' in data:
for child_data in data['children']:
for child_obj in self.create_class(child_data):
for child_obj in self.create_class(child_data, options=options):
obj.children.append(child_obj)
yield obj
class JavaScriptBase(AutoAPIBase):
class JavaScriptPythonMapper(PythonMapperBase):
language = 'javascript'
def __init__(self, obj):
def __init__(self, obj, **kwargs):
'''
Map JSON data into Python object.
@ -84,7 +84,7 @@ class JavaScriptBase(AutoAPIBase):
so we try and keep standard naming to keep templates more re-usable.
'''
super(JavaScriptBase, self).__init__(obj)
super(JavaScriptPythonMapper, self).__init__(obj, **kwargs)
self.name = obj.get('name')
self.id = self.name
@ -104,27 +104,28 @@ class JavaScriptBase(AutoAPIBase):
pass
class JavaScriptClass(JavaScriptBase):
class JavaScriptClass(JavaScriptPythonMapper):
type = 'class'
ref_directive = 'class'
top_level_object = True
class JavaScriptFunction(JavaScriptBase):
class JavaScriptFunction(JavaScriptPythonMapper):
type = 'function'
ref_type = 'func'
class JavaScriptData(JavaScriptBase):
class JavaScriptData(JavaScriptPythonMapper):
type = 'data'
ref_directive = 'data'
class JavaScriptMember(JavaScriptBase):
class JavaScriptMember(JavaScriptPythonMapper):
type = 'member'
ref_directive = 'member'
class JavaScriptAttribute(JavaScriptBase):
class JavaScriptAttribute(JavaScriptPythonMapper):
type = 'attribute'
ref_directive = 'attr'

55
autoapi/domains/python.py → autoapi/mappers/python.py
View File

@ -2,10 +2,10 @@ from collections import defaultdict
from epyparse import parsed
from .base import AutoAPIBase, AutoAPIDomain
from .base import PythonMapperBase, SphinxMapperBase
class PythonDomain(AutoAPIDomain):
class PythonSphinxMapper(SphinxMapperBase):
'''Auto API domain handler for Python
@ -26,12 +26,12 @@ class PythonDomain(AutoAPIDomain):
parsed_data = parsed(path)
return parsed_data
except IOError:
print Warning('Error reading file: {0}'.format(path))
self.app.warn('Error reading file: {0}'.format(path))
except TypeError:
print Warning('Error reading file: {0}'.format(path))
self.app.warn('Error reading file: {0}'.format(path))
return None
def create_class(self, data):
def create_class(self, data, options=None, **kwargs):
'''Return instance of class based on Roslyn type property
Data keys handled here:
@ -52,22 +52,22 @@ class PythonDomain(AutoAPIDomain):
except KeyError:
self.app.warn("Unknown Type: %s" % data['type'])
else:
obj = cls(data, jinja_env=self.jinja_env)
obj = cls(data, jinja_env=self.jinja_env, options=self.app.config.autoapi_options)
if 'children' in data:
for child_data in data['children']:
for child_obj in self.create_class(child_data):
for child_obj in self.create_class(child_data, options=options):
obj.children.append(child_obj)
self.add_object(child_obj)
yield obj
class PythonBase(AutoAPIBase):
class PythonPythonMapper(PythonMapperBase):
language = 'python'
def __init__(self, obj, jinja_env):
super(PythonBase, self).__init__(obj)
def __init__(self, obj, **kwargs):
super(PythonPythonMapper, self).__init__(obj, **kwargs)
self.jinja_env = jinja_env
# Always exist
self.id = obj['fullname']
self.name = self.obj.get('fullname', self.id)
@ -75,21 +75,46 @@ class PythonBase(AutoAPIBase):
# Optional
self.imports = obj.get('imports', [])
self.children = []
self.parameters = obj.get('params', [])
self.args = obj.get('args', [])
self.params = obj.get('params', [])
self.docstring = obj.get('docstring', '')
self.methods = obj.get('methods', [])
self.inheritance = obj.get('bases', [])
# For later
self.item_map = defaultdict(list)
@property
def undoc_member(self):
return self.docstring == ''
class PythonFunction(PythonBase):
@property
def private_member(self):
return self.short_name[0] == '_'
@property
def special_member(self):
return self.short_name[0:2] == '__'
@property
def display(self):
if self.undoc_member and 'undoc-members' not in self.options:
return False
if self.private_member and 'private-members' not in self.options:
return False
if self.special_member and 'special-members' not in self.options:
return False
return True
class PythonFunction(PythonPythonMapper):
type = 'function'
class PythonModule(PythonBase):
class PythonModule(PythonPythonMapper):
type = 'module'
top_level_object = True
class PythonClass(PythonBase):
class PythonClass(PythonPythonMapper):
type = 'class'

6
autoapi/settings.py
View File

@ -1,3 +1,9 @@
"""
Basic settings for AutoAPI projects.
You shouldn't need to touch this.
"""
import os
SITE_ROOT = os.path.dirname(os.path.realpath(__file__))

7
autoapi/templates/index.rst
View File

@ -9,7 +9,8 @@ Below is a list of all items that are documented here.
:glob:
:maxdepth: 1
*/*
{% for page in pages|sort %}
{%- for page in pages|sort %}
{% if page.top_level_object %}
/autoapi/{{ page.id.split('.')|join('/') }}/index
{% endfor %}
{% endif %}
{%- endfor %}

31
autoapi/templates/python/class.rst
View File

@ -1,6 +1,19 @@
.. py:class:: {{ obj.name }}{% if obj.args %}({{ obj.args|join(',') }}){% endif %}
{{ obj.short_name }}
{{ "-" * obj.short_name|length }}
{% if obj.docstring %}
.. py:class:: {{ obj.short_name }}{% if obj.args %}({{ obj.args|join(',') }}){% endif %}
{%- if obj.inheritance %}
.. rubric:: Imports
{% for import in obj.inheritance %}
* {{ import }}
{% endfor %}
{% endif %}
{%- if obj.docstring %}
.. rubric:: Summary
@ -8,24 +21,20 @@
{% endif %}
{% if obj.methods %}
{%- if obj.methods %}
{% for method in obj.methods %}
{%- for method in obj.methods %}
{% macro render() %}{{ method.render() }}{% endmacro %}
{{ render()|indent(3) }}
{{ method.rendered|indent(3) }}
{%- endfor %}
{% endif %}
{% block content %}
{%- for obj_item in obj.children|sort %}
{%- for obj_item in obj.children %}
{% macro render() %}{{ obj_item.render() }}{% endmacro %}
{{ render()|indent(0) }}
{{ obj_item.rendered|indent(3) }}
{%- endfor %}
{% endblock %}

14
autoapi/templates/python/function.rst
View File

@ -1,14 +1,14 @@
{# Identention in this file is important #}
{%- if obj.display %}
{% if is_method %}
{%- if is_method %}
{# Slice self off #}
.. method:: {{ obj.name.split('.')[-1] }}({{ args[1:]|join(',') }})
.. method:: {{ obj.name.split('.')[-1] }}({{ obj.args[1:]|join(',') }})
{% else %}
.. function:: {{ obj.name.split('.')[-1] }}({{ args|join(',') }})
.. function:: {{ obj.name.split('.')[-1] }}({{ obj.args|join(',') }})
{% endif %}
{% if obj.docstring %}
{{ obj.docstring|indent(3) }}
{%- if obj.docstring %}
{{ obj.docstring.strip()|indent(3) }}
{% endif %}
{% endif %}

2
autoapi/templates/python/member.rst
View File

@ -1,3 +1,5 @@
.. Member Template
{# Identention in this file is important #}
.. {{ obj.type }}:: {{ obj.name }}

23
autoapi/templates/python/module.rst
View File

@ -1,22 +1,18 @@
{{ obj.name }}
{{ "-" * obj.name|length }}
{{ "~" * obj.name|length }}
{% block toc %}
{% if obj.children %}
{%- if obj.imports %}
.. toctree::
:maxdepth: 4
.. rubric:: Imports
{% for item in obj.children|sort %}
/autoapi/{{ item.id.split('.')|join('/') }}/index
{%- endfor %}
{% for import in obj.imports %}
* {{ import }}
{% endfor %}
{% endif %}
{% endblock %}
{% if obj.docstring %}
{%- if obj.docstring %}
.. rubric:: Summary
@ -30,10 +26,9 @@
{% block content %}
{%- for obj_item in obj.children|sort %}
{%- for obj_item in obj.children %}
{% macro render() %}{{ obj_item.render() }}{% endmacro %}
{{ render()|indent(0) }}
{{ obj_item.rendered|indent(0) }}
{%- endfor %}
{% endblock %}

10
docs/conf.py
View File

@ -12,15 +12,6 @@
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
import shlex
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
@ -34,6 +25,7 @@ extensions = ['autoapi.extension']
autoapi_type = 'python'
autoapi_dir = '../autoapi'
autoapi_file_pattern = '*.py'
autoapi_options = ['members', 'undoc-members', 'private-members']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

11
docs/config.rst
View File

@ -38,3 +38,14 @@ AutoAPI Configuration
Keep the AutoAPI generated files on the filesystem after the run.
Useful for debugging.
.. confval:: autoapi_options
Default: ``['members', 'undoc-members', 'private-members', 'special-members']``
Options for display of the documentation.
:param members: Display children of an object
:param undoc-members: Display undocumented object
:param private-members: Display private objects (_foo in Python)
:param special-members: Display special objects (__foo__ in Python)

195
tests/dotnetexample/Makefile Normal file
View File

@ -0,0 +1,195 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS = -v -v
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SphinxAutoAPI.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SphinxAutoAPI.qhc"
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/SphinxAutoAPI"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SphinxAutoAPI"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
livehtml:
sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

22
tests/dotnetexample/conf.py Normal file
View File

@ -0,0 +1,22 @@
# -*- coding: utf-8 -*-
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
project = u'dotnetexample'
copyright = u'2015, rtfd'
author = u'rtfd'
version = '0.1'
release = '0.1'
language = None
exclude_patterns = ['_build']
pygments_style = 'sphinx'
todo_include_todos = False
html_theme = 'alabaster'
html_static_path = ['_static']
htmlhelp_basename = 'dotnetexampledoc'
extensions = ['autoapi.extension', 'sphinxcontrib.dotnetdomain']
autoapi_type = 'dotnet'
autoapi_dir = 'example'
autoapi_file_pattern = '*.yml'

372
tests/dotnetexample/example/Microsoft.CodeAnalysis.AdhocWorkspace.yml Executable file
View File

@ -0,0 +1,372 @@
items:
- uid: Microsoft.CodeAnalysis.AdhocWorkspace
href: Microsoft.CodeAnalysis.AdhocWorkspace.yml
name: AdhocWorkspace
fullName: Microsoft.CodeAnalysis.AdhocWorkspace
type: Class
source:
remote: &o0
branch: master
repo: https://github.com/chenkennt/roslyn.git
description: v1.0-12-gef085ea
path: src/Workspaces/Core/Portable/Workspace/AdhocWorkspace.cs
startLine: 16
summary: >-
A workspace that allows full manipulation of projects and documents,
but does not persist changes.
syntax:
content:
CSharp: public sealed class AdhocWorkspace
inheritance:
- id: System.Object
name: System.Object
isExternal: true
- id: Microsoft.CodeAnalysis.Workspace
name: Workspace
href: Microsoft.CodeAnalysis.Workspace.yml
id: Microsoft.CodeAnalysis.AdhocWorkspace
children:
- Microsoft.CodeAnalysis.AdhocWorkspace.#ctor(Microsoft.CodeAnalysis.Host.HostServices,System.String)
- Microsoft.CodeAnalysis.AdhocWorkspace.#ctor
- Microsoft.CodeAnalysis.AdhocWorkspace.CanApplyChange(Microsoft.CodeAnalysis.ApplyChangesKind)
- Microsoft.CodeAnalysis.AdhocWorkspace.CanOpenDocuments
- Microsoft.CodeAnalysis.AdhocWorkspace.ClearSolution
- Microsoft.CodeAnalysis.AdhocWorkspace.AddSolution(Microsoft.CodeAnalysis.SolutionInfo)
- Microsoft.CodeAnalysis.AdhocWorkspace.AddProject(System.String,System.String)
- Microsoft.CodeAnalysis.AdhocWorkspace.AddProject(Microsoft.CodeAnalysis.ProjectInfo)
- Microsoft.CodeAnalysis.AdhocWorkspace.AddProjects(System.Collections.Generic.IEnumerable{Microsoft.CodeAnalysis.ProjectInfo})
- Microsoft.CodeAnalysis.AdhocWorkspace.AddDocument(Microsoft.CodeAnalysis.ProjectId,System.String,Microsoft.CodeAnalysis.Text.SourceText)
- Microsoft.CodeAnalysis.AdhocWorkspace.AddDocument(Microsoft.CodeAnalysis.DocumentInfo)
- Microsoft.CodeAnalysis.AdhocWorkspace.OpenDocument(Microsoft.CodeAnalysis.DocumentId,System.Boolean)
- Microsoft.CodeAnalysis.AdhocWorkspace.CloseDocument(Microsoft.CodeAnalysis.DocumentId)
- Microsoft.CodeAnalysis.AdhocWorkspace.OpenAdditionalDocument(Microsoft.CodeAnalysis.DocumentId,System.Boolean)
- Microsoft.CodeAnalysis.AdhocWorkspace.CloseAdditionalDocument(Microsoft.CodeAnalysis.DocumentId)
- uid: Microsoft.CodeAnalysis.AdhocWorkspace.#ctor(Microsoft.CodeAnalysis.Host.HostServices,System.String)
href: Microsoft.CodeAnalysis.AdhocWorkspace.yml
name: AdhocWorkspace(HostServices, string)
fullName: Microsoft.CodeAnalysis.AdhocWorkspace.AdhocWorkspace(Microsoft.CodeAnalysis.Host.HostServices, string)
type: Constructor
source:
remote: *o0
path: src/Workspaces/Core/Portable/Workspace/AdhocWorkspace.cs
startLine: 18
syntax:
content:
CSharp: 'public AdhocWorkspace(HostServices host, string workspaceKind = "Custom"): base (host, workspaceKind)'
parameters:
- id: host
type:
id: Microsoft.CodeAnalysis.Host.HostServices
name: HostServices
href: Microsoft.CodeAnalysis.Host.HostServices.yml
- id: workspaceKind
type:
id: System.String
name: System.String
isExternal: true
id: Microsoft.CodeAnalysis.AdhocWorkspace.#ctor(Microsoft.CodeAnalysis.Host.HostServices,System.String)
- uid: Microsoft.CodeAnalysis.AdhocWorkspace.#ctor
href: Microsoft.CodeAnalysis.AdhocWorkspace.yml
name: AdhocWorkspace()
fullName: Microsoft.CodeAnalysis.AdhocWorkspace.AdhocWorkspace()
type: Constructor
source:
remote: *o0
path: src/Workspaces/Core/Portable/Workspace/AdhocWorkspace.cs
startLine: 23
syntax:
content:
CSharp: 'public AdhocWorkspace(): this (Host.Mef.MefHostServices.DefaultHost)'
parameters: []
id: Microsoft.CodeAnalysis.AdhocWorkspace.#ctor
- uid: Microsoft.CodeAnalysis.AdhocWorkspace.CanApplyChange(Microsoft.CodeAnalysis.ApplyChangesKind)
href: Microsoft.CodeAnalysis.AdhocWorkspace.yml
name: CanApplyChange(ApplyChangesKind)
fullName: Microsoft.CodeAnalysis.AdhocWorkspace.CanApplyChange(Microsoft.CodeAnalysis.ApplyChangesKind)
type: Method
source:
remote: *o0
path: src/Workspaces/Core/Portable/Workspace/AdhocWorkspace.cs
startLine: 28
syntax:
content:
CSharp: public override bool CanApplyChange(ApplyChangesKind feature)
parameters:
- id: feature
type:
id: Microsoft.CodeAnalysis.ApplyChangesKind
name: ApplyChangesKind
href: Microsoft.CodeAnalysis.ApplyChangesKind.yml
return:
id: Boolean
id: Microsoft.CodeAnalysis.AdhocWorkspace.CanApplyChange(Microsoft.CodeAnalysis.ApplyChangesKind)
- uid: Microsoft.CodeAnalysis.AdhocWorkspace.CanOpenDocuments
href: Microsoft.CodeAnalysis.AdhocWorkspace.yml
name: CanOpenDocuments
fullName: Microsoft.CodeAnalysis.AdhocWorkspace.CanOpenDocuments
type: Property
source:
remote: *o0
path: src/Workspaces/Core/Portable/Workspace/AdhocWorkspace.cs
startLine: 34
syntax:
content:
CSharp: public override bool CanOpenDocuments { get; }
parameters:
- id: CanOpenDocuments
type:
id: System.Boolean
name: System.Boolean
isExternal: true
id: Microsoft.CodeAnalysis.AdhocWorkspace.CanOpenDocuments
- uid: Microsoft.CodeAnalysis.AdhocWorkspace.ClearSolution
href: Microsoft.CodeAnalysis.AdhocWorkspace.yml
name: ClearSolution()
fullName: Microsoft.CodeAnalysis.AdhocWorkspace.ClearSolution()
type: Method
source:
remote: *o0
path: src/Workspaces/Core/Portable/Workspace/AdhocWorkspace.cs
startLine: 46
summary: Clears all projects and documents from the workspace.
syntax:
content:
CSharp: public new void ClearSolution()
parameters: []
id: Microsoft.CodeAnalysis.AdhocWorkspace.ClearSolution
- uid: Microsoft.CodeAnalysis.AdhocWorkspace.AddSolution(Microsoft.CodeAnalysis.SolutionInfo)
href: Microsoft.CodeAnalysis.AdhocWorkspace.yml
name: AddSolution(SolutionInfo)
fullName: Microsoft.CodeAnalysis.AdhocWorkspace.AddSolution(Microsoft.CodeAnalysis.SolutionInfo)
type: Method
source:
remote: *o0
path: src/Workspaces/Core/Portable/Workspace/AdhocWorkspace.cs
startLine: 54
summary: Adds an entire solution to the workspace, replacing any existing solution.
syntax:
content:
CSharp: public Solution AddSolution(SolutionInfo solutionInfo)
parameters:
- id: solutionInfo
type:
id: Microsoft.CodeAnalysis.SolutionInfo
name: SolutionInfo
href: Microsoft.CodeAnalysis.SolutionInfo.yml
return:
id: Solution
id: Microsoft.CodeAnalysis.AdhocWorkspace.AddSolution(Microsoft.CodeAnalysis.SolutionInfo)
- uid: Microsoft.CodeAnalysis.AdhocWorkspace.AddProject(System.String,System.String)
href: Microsoft.CodeAnalysis.AdhocWorkspace.yml
name: AddProject(string, string)
fullName: Microsoft.CodeAnalysis.AdhocWorkspace.AddProject(string, string)
type: Method
source:
remote: *o0
path: src/Workspaces/Core/Portable/Workspace/AdhocWorkspace.cs
startLine: 69
summary: Adds a project to the workspace. All previous projects remain intact.
syntax:
content:
CSharp: public Project AddProject(string name, string language)
parameters:
- id: name
type:
id: System.String
name: System.String
isExternal: true
- id: language
type:
id: System.String
name: System.String
isExternal: true
return:
id: Project
id: Microsoft.CodeAnalysis.AdhocWorkspace.AddProject(System.String,System.String)
- uid: Microsoft.CodeAnalysis.AdhocWorkspace.AddProject(Microsoft.CodeAnalysis.ProjectInfo)
href: Microsoft.CodeAnalysis.AdhocWorkspace.yml
name: AddProject(ProjectInfo)
fullName: Microsoft.CodeAnalysis.AdhocWorkspace.AddProject(Microsoft.CodeAnalysis.ProjectInfo)
type: Method
source:
remote: *o0
path: src/Workspaces/Core/Portable/Workspace/AdhocWorkspace.cs
startLine: 78
summary: Adds a project to the workspace. All previous projects remain intact.
syntax:
content:
CSharp: public Project AddProject(ProjectInfo projectInfo)
parameters:
- id: projectInfo
type:
id: Microsoft.CodeAnalysis.ProjectInfo
name: ProjectInfo
href: Microsoft.CodeAnalysis.ProjectInfo.yml
return:
id: Project
id: Microsoft.CodeAnalysis.AdhocWorkspace.AddProject(Microsoft.CodeAnalysis.ProjectInfo)
- uid: Microsoft.CodeAnalysis.AdhocWorkspace.AddProjects(System.Collections.Generic.IEnumerable{Microsoft.CodeAnalysis.ProjectInfo})
href: Microsoft.CodeAnalysis.AdhocWorkspace.yml
name: AddProjects(IEnumerable<ProjectInfo>)
fullName: Microsoft.CodeAnalysis.AdhocWorkspace.AddProjects(System.Collections.Generic.IEnumerable<Microsoft.CodeAnalysis.ProjectInfo>)
type: Method
source:
remote: *o0
path: src/Workspaces/Core/Portable/Workspace/AdhocWorkspace.cs
startLine: 94
summary: Adds multiple projects to the workspace at once. All existing projects remain intact.
syntax:
content:
CSharp: public void AddProjects(IEnumerable<ProjectInfo> projectInfos)
parameters:
- id: projectInfos
type:
id: System.Collections.Generic.IEnumerable{Microsoft.CodeAnalysis.ProjectInfo}
name: System.Collections.Generic.IEnumerable{Microsoft.CodeAnalysis.ProjectInfo}
isExternal: true
id: Microsoft.CodeAnalysis.AdhocWorkspace.AddProjects(System.Collections.Generic.IEnumerable{Microsoft.CodeAnalysis.ProjectInfo})
- uid: Microsoft.CodeAnalysis.AdhocWorkspace.AddDocument(Microsoft.CodeAnalysis.ProjectId,System.String,Microsoft.CodeAnalysis.Text.SourceText)
href: Microsoft.CodeAnalysis.AdhocWorkspace.yml
name: AddDocument(ProjectId, string, SourceText)
fullName: Microsoft.CodeAnalysis.AdhocWorkspace.AddDocument(Microsoft.CodeAnalysis.ProjectId, string, Microsoft.CodeAnalysis.Text.SourceText)
type: Method
source:
remote: *o0
path: src/Workspaces/Core/Portable/Workspace/AdhocWorkspace.cs
startLine: 110
summary: Adds a document to the workspace.
syntax:
content:
CSharp: public Document AddDocument(ProjectId projectId, string name, SourceText text)
parameters:
- id: projectId
type:
id: Microsoft.CodeAnalysis.ProjectId
name: ProjectId
href: Microsoft.CodeAnalysis.ProjectId.yml
- id: name
type:
id: System.String
name: System.String
isExternal: true
- id: text
type:
id: Microsoft.CodeAnalysis.Text.SourceText
name: SourceText
href: Microsoft.CodeAnalysis.Text.SourceText
return:
id: Document
id: Microsoft.CodeAnalysis.AdhocWorkspace.AddDocument(Microsoft.CodeAnalysis.ProjectId,System.String,Microsoft.CodeAnalysis.Text.SourceText)
- uid: Microsoft.CodeAnalysis.AdhocWorkspace.AddDocument(Microsoft.CodeAnalysis.DocumentInfo)
href: Microsoft.CodeAnalysis.AdhocWorkspace.yml
name: AddDocument(DocumentInfo)
fullName: Microsoft.CodeAnalysis.AdhocWorkspace.AddDocument(Microsoft.CodeAnalysis.DocumentInfo)
type: Method
source:
remote: *o0
path: src/Workspaces/Core/Portable/Workspace/AdhocWorkspace.cs
startLine: 136
summary: Adds a document to the workspace.
syntax:
content:
CSharp: public Document AddDocument(DocumentInfo documentInfo)
parameters:
- id: documentInfo
type:
id: Microsoft.CodeAnalysis.DocumentInfo
name: DocumentInfo
href: Microsoft.CodeAnalysis.DocumentInfo.yml
return:
id: Document
id: Microsoft.CodeAnalysis.AdhocWorkspace.AddDocument(Microsoft.CodeAnalysis.DocumentInfo)
- uid: Microsoft.CodeAnalysis.AdhocWorkspace.OpenDocument(Microsoft.CodeAnalysis.DocumentId,System.Boolean)
href: Microsoft.CodeAnalysis.AdhocWorkspace.yml
name: OpenDocument(DocumentId, bool)
fullName: Microsoft.CodeAnalysis.AdhocWorkspace.OpenDocument(Microsoft.CodeAnalysis.DocumentId, bool)
type: Method
source:
remote: *o0
path: src/Workspaces/Core/Portable/Workspace/AdhocWorkspace.cs
startLine: 151
summary: Puts the specified document into the open state.
syntax:
content:
CSharp: public override void OpenDocument(DocumentId documentId, bool activate = true)
parameters:
- id: documentId
type:
id: Microsoft.CodeAnalysis.DocumentId
name: DocumentId
href: Microsoft.CodeAnalysis.DocumentId.yml
- id: activate
type:
id: System.Boolean
name: System.Boolean
isExternal: true
id: Microsoft.CodeAnalysis.AdhocWorkspace.OpenDocument(Microsoft.CodeAnalysis.DocumentId,System.Boolean)
- uid: Microsoft.CodeAnalysis.AdhocWorkspace.CloseDocument(Microsoft.CodeAnalysis.DocumentId)
href: Microsoft.CodeAnalysis.AdhocWorkspace.yml
name: CloseDocument(DocumentId)
fullName: Microsoft.CodeAnalysis.AdhocWorkspace.CloseDocument(Microsoft.CodeAnalysis.DocumentId)
type: Method
source:
remote: *o0
path: src/Workspaces/Core/Portable/Workspace/AdhocWorkspace.cs
startLine: 164
summary: Puts the specified document into the closed state.
syntax:
content:
CSharp: public override void CloseDocument(DocumentId documentId)
parameters:
- id: documentId
type:
id: Microsoft.CodeAnalysis.DocumentId
name: DocumentId
href: Microsoft.CodeAnalysis.DocumentId.yml
id: Microsoft.CodeAnalysis.AdhocWorkspace.CloseDocument(Microsoft.CodeAnalysis.DocumentId)
- uid: Microsoft.CodeAnalysis.AdhocWorkspace.OpenAdditionalDocument(Microsoft.CodeAnalysis.DocumentId,System.Boolean)
href: Microsoft.CodeAnalysis.AdhocWorkspace.yml
name: OpenAdditionalDocument(DocumentId, bool)
fullName: Microsoft.CodeAnalysis.AdhocWorkspace.OpenAdditionalDocument(Microsoft.CodeAnalysis.DocumentId, bool)
type: Method
source:
remote: *o0
path: src/Workspaces/Core/Portable/Workspace/AdhocWorkspace.cs
startLine: 179
summary: Puts the specified additional document into the open state.
syntax:
content:
CSharp: public override void OpenAdditionalDocument(DocumentId documentId, bool activate = true)
parameters:
- id: documentId
type:
id: Microsoft.CodeAnalysis.DocumentId
name: DocumentId
href: Microsoft.CodeAnalysis.DocumentId.yml
- id: activate
type:
id: System.Boolean
name: System.Boolean
isExternal: true
id: Microsoft.CodeAnalysis.AdhocWorkspace.OpenAdditionalDocument(Microsoft.CodeAnalysis.DocumentId,System.Boolean)
- uid: Microsoft.CodeAnalysis.AdhocWorkspace.CloseAdditionalDocument(Microsoft.CodeAnalysis.DocumentId)
href: Microsoft.CodeAnalysis.AdhocWorkspace.yml
name: CloseAdditionalDocument(DocumentId)
fullName: Microsoft.CodeAnalysis.AdhocWorkspace.CloseAdditionalDocument(Microsoft.CodeAnalysis.DocumentId)
type: Method
source:
remote: *o0
path: src/Workspaces/Core/Portable/Workspace/AdhocWorkspace.cs
startLine: 192
summary: Puts the specified additional document into the closed state
syntax:
content:
CSharp: public override void CloseAdditionalDocument(DocumentId documentId)
parameters:
- id: documentId
type:
id: Microsoft.CodeAnalysis.DocumentId
name: DocumentId
href: Microsoft.CodeAnalysis.DocumentId.yml
id: Microsoft.CodeAnalysis.AdhocWorkspace.CloseAdditionalDocument(Microsoft.CodeAnalysis.DocumentId)

13
tests/dotnetexample/index.rst Normal file
View File

@ -0,0 +1,13 @@
Welcome to .Net example's documentation!
========================================
.. toctree::
autoapi/index
Contents:
.. toctree::
:maxdepth: 2

195
tests/goexample/Makefile Normal file
View File

@ -0,0 +1,195 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS = -v -v
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SphinxAutoAPI.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SphinxAutoAPI.qhc"
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/SphinxAutoAPI"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SphinxAutoAPI"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
livehtml:
sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

22
tests/goexample/conf.py Normal file
View File

@ -0,0 +1,22 @@
# -*- coding: utf-8 -*-
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
project = u'goexample'
copyright = u'2015, rtfd'
author = u'rtfd'
version = '0.1'
release = '0.1'
language = None
exclude_patterns = ['_build']
pygments_style = 'sphinx'
todo_include_todos = False
html_theme = 'alabaster'
html_static_path = ['_static']
htmlhelp_basename = 'goexampledoc'
extensions = ['autoapi.extension', 'sphinxcontrib.golangdomain']
autoapi_type = 'go'
autoapi_dir = 'example'
autoapi_file_pattern = '*.go'

174
tests/goexample/example/godocjson.go Normal file
View File

@ -0,0 +1,174 @@
package main
import (
"encoding/json"
"fmt"
"go/doc"
"go/parser"
"go/token"
"os"
)
// Func represents a function declaration.
type Func struct {
Doc string `json:"doc"`
Name string `json:"name"`
PackageName string `json:"packageName"`
PackageImportPath string `json:"packageImportPath"`
// Decl *ast.FuncDecl
// methods
// (for functions, these fields have the respective zero value)
Recv string `json:"recv"` // actual receiver "T" or "*T"
Orig string `json:"orig"` // original receiver "T" or "*T"
// Level int // embedding level; 0 means not embedded
}
// Package represents a package declaration.
type Package struct {
Type string `json:"type"`
Doc string `json:"doc"`
Name string `json:"name"`
ImportPath string `json:"importPath"`
Imports []string `json:"imports"`
Filenames []string `json:"filenames"`
Notes map[string][]*Note `json:"notes"`
// DEPRECATED. For backward compatibility Bugs is still populated,
// but all new code should use Notes instead.
Bugs []string `json:"bugs"`
// declarations
Consts []*Value `json:"consts"`
Types []*Type `json:"types"`
Vars []*Value `json:"vars"`
Funcs []*Func `json:"funcs"`
}
// Note represents a note comment.
type Note struct {
Pos token.Pos `json:"pos"`
End token.Pos `json:"end"` // position range of the comment containing the marker
UID string `json:"uid"` // uid found with the marker
Body string `json:"body"` // note body text
}
// Type represents a type declaration.
type Type struct {
PackageName string `json:"packageName"`
PackageImportPath string `json:"packageImportPath"`
Doc string `json:"doc"`
Name string `json:"name"`
// Decl *ast.GenDecl
// associated declarations
Consts []*Value `json:"consts"` // sorted list of constants of (mostly) this type
Vars []*Value `json:"vars"` // sorted list of variables of (mostly) this type
Funcs []*Func `json:"funcs"` // sorted list of functions returning this type
Methods []*Func `json:"methods"` // sorted list of methods (including embedded ones) of this type
}
// Value represents a value declaration.
type Value struct {
PackageName string `json:"packageName"`
PackageImportPath string `json:"packageImportPath"`
Doc string `json:"doc"`
Names []string `json:"names"` // var or const names in declaration order
// Decl *ast.GenDecl
}
// CopyFuncs produces a json-annotated array of Func objects from an array of GoDoc Func objects.
func CopyFuncs(f []*doc.Func, packageName string, packageImportPath string) []*Func {
newFuncs := make([]*Func, len(f))
for i, n := range f {
newFuncs[i] = &Func{
Doc: n.Doc,
Name: n.Name,
PackageName: packageName,
PackageImportPath: packageImportPath,
Orig: n.Orig,
Recv: n.Recv,
}
}
return newFuncs
}
// CopyValues produces a json-annotated array of Value objects from an array of GoDoc Value objects.
func CopyValues(c []*doc.Value, packageName string, packageImportPath string) []*Value {
newConsts := make([]*Value, len(c))
for i, c := range c {
newConsts[i] = &Value{
Doc: c.Doc,
Names: c.Names,
PackageName: packageName,
PackageImportPath: packageImportPath,
}
}
return newConsts
}
// CopyPackage produces a json-annotated Package object from a GoDoc Package object.
func CopyPackage(pkg *doc.Package) Package {
newPkg := Package{
Type: "package",
Doc: pkg.Doc,
Name: pkg.Name,
ImportPath: pkg.ImportPath,
Imports: pkg.Imports,
Filenames: pkg.Filenames,
Bugs: pkg.Bugs,
}
newPkg.Notes = map[string][]*Note{}
for key, value := range pkg.Notes {
notes := make([]*Note, len(value))
for i, note := range value {
notes[i] = &Note{
Pos: note.Pos,
End: note.End,
UID: note.UID,
Body: note.Body,
}
}
newPkg.Notes[key] = notes
}
newPkg.Consts = CopyValues(pkg.Consts, pkg.Name, pkg.ImportPath)
newPkg.Funcs = CopyFuncs(pkg.Funcs, pkg.Name, pkg.ImportPath)
newPkg.Types = make([]*Type, len(pkg.Types))
for i, t := range pkg.Types {
newPkg.Types[i] = &Type{
Name: t.Name,
PackageName: pkg.Name,
PackageImportPath: pkg.ImportPath,
Consts: CopyValues(t.Consts, pkg.Name, pkg.ImportPath),
Doc: t.Doc,
Funcs: CopyFuncs(t.Funcs, pkg.Name, pkg.ImportPath),
Methods: CopyFuncs(t.Methods, pkg.Name, pkg.ImportPath),
Vars: CopyValues(t.Vars, pkg.Name, pkg.ImportPath),
}
}
newPkg.Vars = CopyValues(pkg.Vars, pkg.Name, pkg.ImportPath)
return newPkg
}
func main() {
directories := os.Args[1:]
for _, dir := range directories {
fileSet := token.NewFileSet()
pkgs, firstError := parser.ParseDir(fileSet, dir, nil, parser.ParseComments|parser.AllErrors)
if firstError != nil {
panic(firstError)
}
for _, pkg := range pkgs {
docPkg := doc.New(pkg, dir, 0)
cleanedPkg := CopyPackage(docPkg)
pkgJSON, err := json.MarshalIndent(cleanedPkg, "", " ")
if err != nil {
panic(err)
}
fmt.Printf("%s\n", pkgJSON)
}
}
}

13
tests/goexample/index.rst Normal file
View File

@ -0,0 +1,13 @@
Welcome to Go example's documentation!
======================================
.. toctree::
autoapi/index
Contents:
.. toctree::
:maxdepth: 2

195
tests/jsexample/Makefile Normal file
View File

@ -0,0 +1,195 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS = -v -v
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SphinxAutoAPI.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SphinxAutoAPI.qhc"
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/SphinxAutoAPI"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SphinxAutoAPI"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
livehtml:
sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

195
tests/pyexample/Makefile Normal file
View File

@ -0,0 +1,195 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS = -v -v
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SphinxAutoAPI.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SphinxAutoAPI.qhc"
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/SphinxAutoAPI"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SphinxAutoAPI"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
livehtml:
sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

195
tests/templateexample/Makefile Normal file
View File

@ -0,0 +1,195 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS = -v -v
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SphinxAutoAPI.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SphinxAutoAPI.qhc"
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/SphinxAutoAPI"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SphinxAutoAPI"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
livehtml:
sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

24
tests/templateexample/conf.py Normal file
View File

@ -0,0 +1,24 @@
# -*- coding: utf-8 -*-
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
project = u'pyexample'
copyright = u'2015, rtfd'
author = u'rtfd'
version = '0.1'
release = '0.1'
language = None
exclude_patterns = ['_build']
pygments_style = 'sphinx'
todo_include_todos = False
html_theme = 'alabaster'
html_static_path = ['_static']
htmlhelp_basename = 'pyexampledoc'
extensions = ['autoapi.extension']
autoapi_type = 'python'
autoapi_dir = 'example'
autoapi_file_pattern = '*.py'
autoapi_template_dir = 'template_overrides'
exclude_patterns = [autoapi_template_dir]

7
tests/templateexample/example/example.py Normal file
View File

@ -0,0 +1,7 @@
__author__ = 'swenson'
import math
def example_function(x):
"""Compute the square root of x and return it."""
return math.sqrt(x)

26
tests/templateexample/index.rst Normal file
View File

@ -0,0 +1,26 @@
.. pyexample documentation master file, created by
sphinx-quickstart on Fri May 29 13:34:37 2015.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to pyexample's documentation!
=====================================
.. toctree::
autoapi/index
Contents:
.. toctree::
:maxdepth: 2
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

1
tests/templateexample/template_overrides/python/function.rst Normal file
View File

@ -0,0 +1 @@
This is a fuction template override!

35
tests/test_dotnet_domain.py → tests/test_domains.py
View File

@ -1,12 +1,11 @@
'''Test .NET autoapi domain'''
import unittest
import time
from contextlib import nested
from mock import patch
from autoapi.domains import dotnet
from autoapi.mappers import dotnet
class DomainTests(unittest.TestCase):
@ -25,15 +24,10 @@ class DomainTests(unittest.TestCase):
self.application = _application()
def test_config(self):
'''Sphinx app config'''
dom = dotnet.DotNetDomain(self.application)
self.assertEqual(dom.get_config('autoapi_dir'), '/tmp/autoapi/tmp')
self.assertEqual(dom.get_config('autoapi_dir'), '/tmp/autoapi/tmp')
def test_create_class(self):
'''Test .NET class instance creation helper'''
dom = dotnet.DotNetDomain(self.application)
dom = dotnet.DotNetSphinxMapper(self.application)
def _create_class(data):
return list(dom.create_class(data))[0]
cls = _create_class({'id': 'Foo.Bar', 'type': 'Namespace'})
@ -60,7 +54,8 @@ class DomainTests(unittest.TestCase):
self.assertIsInstance(cls, dotnet.DotNetEvent)
def test_create_class_with_children(self):
dom = dotnet.DotNetDomain(self.application)
dom = dotnet.DotNetSphinxMapper(self.application)
def _create_class(data):
return list(dom.create_class(data))[0]
cls = _create_class({'id': 'Foo.Bar',
@ -76,7 +71,7 @@ class DomainTests(unittest.TestCase):
'''Test basic get objects'''
objs = []
def _mock_find(self, pattern):
def _mock_find(self, pattern, **kwargs):
return {'items': ['foo', 'bar']}
def _mock_read(self, path):
@ -84,19 +79,13 @@ class DomainTests(unittest.TestCase):
{'id': 'Foo.Bar2', 'name': 'Bar', 'type': 'property'}],
'id': 'Foo.Bar', 'type': 'Class', 'summary': path}
def _mock_add(self, obj):
objs.append(obj)
def _mock_config(self, key):
return 'foo'
with nested(
patch('autoapi.domains.dotnet.DotNetDomain.find_files', _mock_find),
patch('autoapi.domains.dotnet.DotNetDomain.read_file', _mock_read),
patch('autoapi.domains.dotnet.DotNetDomain.get_config', _mock_config),
):
dom = dotnet.DotNetDomain(self.application)
dom.get_objects('*')
patch('autoapi.mappers.dotnet.DotNetSphinxMapper.find_files', _mock_find),
patch('autoapi.mappers.dotnet.DotNetSphinxMapper.read_file', _mock_read),
):
dom = dotnet.DotNetSphinxMapper(self.application)
dom.load('', '', '')
dom.map()
objs = dom.objects
self.assertEqual(len(objs), 2)
self.assertEqual(objs['Foo.Bar'].id, 'Foo.Bar')

40
tests/test_full.py
View File

@ -1,40 +0,0 @@
import os
import shutil
import subprocess as sp
import unittest
__author__ = 'swenson'
class FullPythonTests(unittest.TestCase):
def test_full_py(self):
os.chdir('tests/pyexample')
try:
if os.path.exists('_build'):
shutil.rmtree('_build')
os.mkdir('_build')
sp.check_call('sphinx-build -b text -d ./.doctrees . _build/text', shell=True)
with open('_build/text/autoapi/example/index.txt') as fin:
text = fin.read().strip()
self.assertIn('Compute the square root of x and return it.', text)
finally:
os.chdir('../..')
class FullJavaScriptTests(unittest.TestCase):
def test_full_js(self):
os.chdir('tests/jsexample')
try:
if os.path.exists('_build'):
shutil.rmtree('_build')
os.mkdir('_build')
sp.check_call('sphinx-build -b text -d ./.doctrees . _build/text', shell=True)
with open('_build/text/autoapi/Circle/index.txt') as fin:
text = fin.read().strip()
self.assertIn('Creates an instance of Circle', text)
finally:
os.chdir('../..')

93
tests/test_integration.py Normal file
View File

@ -0,0 +1,93 @@
import os
import shutil
import subprocess as sp
import unittest
__author__ = 'swenson'
class LanguageIntegrationTests(unittest.TestCase):
def test_full_py(self):
os.chdir('tests/pyexample')
try:
if os.path.exists('_build'):
shutil.rmtree('_build')
os.mkdir('_build')
sp.check_call('sphinx-build -b text -d _build/doctrees . _build/text', shell=True)
with open('_build/text/autoapi/example/index.txt') as fin:
text = fin.read().strip()
self.assertIn('Compute the square root of x and return it.', text)
finally:
os.chdir('../..')
def test_full_js(self):
os.chdir('tests/jsexample')
try:
if os.path.exists('_build'):
shutil.rmtree('_build')
os.mkdir('_build')
sp.check_call('sphinx-build -b text -d _build/doctrees . _build/text', shell=True)
with open('_build/text/autoapi/Circle/index.txt') as fin:
text = fin.read().strip()
self.assertIn('Creates an instance of Circle', text)
finally:
os.chdir('../..')
def test_full_go(self):
os.chdir('tests/goexample')
try:
if os.path.exists('_build'):
shutil.rmtree('_build')
os.mkdir('_build')
sp.check_call('sphinx-build -b text -d _build/doctrees . _build/text', shell=True)
with open('_build/text/autoapi/main/index.txt') as fin:
text = fin.read().strip()
self.assertIn(
'CopyFuncs produces a json-annotated array of Func objects',
text
)
finally:
os.chdir('../..')
def test_full_dotnet(self):
os.chdir('tests/dotnetexample')
try:
if os.path.exists('_build'):
shutil.rmtree('_build')
os.mkdir('_build')
sp.check_call('sphinx-build -b text -d _build/doctrees . _build/text', shell=True)
with open('_build/text/autoapi/Microsoft/CodeAnalysis/AdhocWorkspace/index.txt') as fin:
text = fin.read().strip()
self.assertIn(
'A workspace that allows full manipulation of projects and documents',
text
)
finally:
os.chdir('../..')
class FeatureIntegrationTests(unittest.TestCase):
def test_template_override(self):
"""
Test that we are overriding the template properly.
This uses the ``template_overrides/python/function.rst`` template to override content.
"""
os.chdir('tests/templateexample')
try:
if os.path.exists('_build'):
shutil.rmtree('_build')
os.mkdir('_build')
sp.check_call('sphinx-build -b text -d _build/doctrees . _build/text', shell=True)
with open('_build/text/autoapi/example/index.txt') as fin:
text = fin.read().strip()
self.assertIn('This is a fuction template override!', text)
finally:
os.chdir('../..')

4
tests/test_dotnet_objects.py → tests/test_objects.py
View File

@ -1,9 +1,8 @@
'''Test .NET autoapi objects'''
import unittest
import time
from autoapi.domains import dotnet
from autoapi.mappers import dotnet
class NamespaceTests(unittest.TestCase):
@ -65,7 +64,6 @@ class NamespaceTests(unittest.TestCase):
self.assertEqual(obj.ref_type, 'event')
self.assertEqual(obj.ref_directive, 'event')
def test_names(self):
'''Test names of objects'''
obj = dotnet.DotNetNamespace({'id': 'Foo.Bar'})