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

Parse out doc id prefixes and add reference types

Browse Source
This commit is contained in:
Anthony Johnson 2015-08-18 14:30:08 -07:00
parent 9676bd011c
commit 436eb28d9f
2 changed files with 62 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
autoapi/mappers/dotnet.py
View File

@ -13,6 +13,37 @@ from sphinx.errors import ExtensionError
from .base import PythonMapperBase, SphinxMapperBase
# Doc comment patterns
DOC_COMMENT_PATTERN = r'''
\<%(tag)s
\s+%(attr)s="(?P<attr_value>[^"]*?)"
\s*?
(?:
\/\>|
\>(?P<inner>[^\<]*?)\<\/%(tag)s\>
)
'''
DOC_COMMENT_SEE_PATTERN = re.compile(
DOC_COMMENT_PATTERN % {'tag': '(?:see|seealso)',
'attr': 'cref'},
re.X)
DOC_COMMENT_PARAM_PATTERN = re.compile(
DOC_COMMENT_PATTERN % {'tag': '(?:paramref|typeparamref)',
'attr': 'name'},
re.X)
# Comment member identities
# From: https://msdn.microsoft.com/en-us/library/vstudio/fsbx0t7x(v=VS.100).aspx
DOC_COMMENT_IDENTITIES = {
'N': 'ns',
'T': 'ref', # can be any type (class, delegate, enum, etc), so use ref
'F': 'field',
'P': 'prop',
'M': 'meth',
'E': 'event',
}
class DotNetSphinxMapper(SphinxMapperBase):
'''Auto API domain handler for .NET
@ -211,25 +242,6 @@ class DotNetPythonMapper(PythonMapperBase):
language = 'dotnet'
# Doc comment patterns
doc_comment_pattern = r'''
\<%(tag)s
\s+%(attr)s="(?P<attr_value>[^"]*?)"
\s*?
(?:
\/\>|
\>(?P<inner>[^\<]*?)\<\/%(tag)s\>
)
'''
doc_comment_see_pattern = re.compile(
doc_comment_pattern % {'tag': '(?:see|seealso)',
'attr': 'cref'},
re.X)
doc_comment_param_pattern = re.compile(
doc_comment_pattern % {'tag': '(?:paramref|typeparamref)',
'attr': 'name'},
re.X)
def __init__(self, obj, **kwargs):
super(DotNetPythonMapper, self).__init__(obj, **kwargs)
@ -362,9 +374,29 @@ class DotNetPythonMapper(PythonMapperBase):
Reference on XML documentation comment syntax
"""
try:
text = DotNetPythonMapper.doc_comment_see_pattern.sub(
':dn:ref:`\g<attr_value>`', text)
text = DotNetPythonMapper.doc_comment_param_pattern.sub(
while True:
found = DOC_COMMENT_SEE_PATTERN.search(text)
if found is None:
break
ref = found.group('attr_value')
reftype = 'ref'
replacement = ''
# Given the pattern of `\w:\w+`, inspect first letter of
# reference for identity type
if ref[1] == ':' and ref[0] in DOC_COMMENT_IDENTITIES:
reftype = DOC_COMMENT_IDENTITIES[ref[:1]]
ref = ref[2:]
replacement = ':dn:{reftype}:`{ref}`'.format(
reftype=reftype, ref=ref)
elif ref[:2] == '!:':
replacement = ref[2:]
else:
replacement = ':dn:ref:`{ref}`'.format(ref=ref)
text = ''.join([text[:found.start()],
replacement,
text[found.end():]])
text = DOC_COMMENT_PARAM_PATTERN.sub(
'``\g<attr_value>``', text)
except TypeError:
pass

12
tests/test_domains.py
View File

@ -98,12 +98,16 @@ class DomainTests(unittest.TestCase):
self.assertEqual(ret, 'This is an example comment :dn:ref:`FOO`')
ret = dotnet.DotNetPythonMapper.transform_doc_comments(
'This is an example comment <see cref="FOO">inner foo</see>')
self.assertEqual(ret, 'This is an example comment :dn:ref:`FOO`')
'This is an example comment <see cref="!:FOO" />')
self.assertEqual(ret, 'This is an example comment FOO')
ret = dotnet.DotNetPythonMapper.transform_doc_comments(
'Test <see cref="FOO" /> and <see cref="BAR">Blah</see>')
self.assertEqual(ret, 'Test :dn:ref:`FOO` and :dn:ref:`BAR`')
'This is an example comment <see cref="N:FOO">inner foo</see>')
self.assertEqual(ret, 'This is an example comment :dn:ns:`FOO`')
ret = dotnet.DotNetPythonMapper.transform_doc_comments(
'Test <see cref="P:FOO" /> and <see cref="E:BAR">Blah</see>')
self.assertEqual(ret, 'Test :dn:prop:`FOO` and :dn:event:`BAR`')
ret = dotnet.DotNetPythonMapper.transform_doc_comments(
'This is an example comment <paramref name="FOO" />')