diff --git a/doc/_static/wsme.css b/doc/_static/wsme.css index 09675f6..43b6b5d 100644 --- a/doc/_static/wsme.css +++ b/doc/_static/wsme.css @@ -1,4 +1,4 @@ -@import "agogo.css"; +@import "sphinxdoc.css"; table.docutils { margin: 0; diff --git a/doc/conf.py b/doc/conf.py index be53305..a92dd83 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -25,7 +25,7 @@ sys.path.insert(0, os.path.abspath('..')) # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'wsme.sphinxext'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -92,7 +92,7 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'agogo' +html_theme = 'sphinxdoc' html_style = 'wsme.css' @@ -106,7 +106,7 @@ html_style = 'wsme.css' # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -#html_title = None +html_title = "WSME %s" % release # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None diff --git a/doc/document.rst b/doc/document.rst new file mode 100644 index 0000000..7cfe789 --- /dev/null +++ b/doc/document.rst @@ -0,0 +1,13 @@ +Document your API +================= + +.. default-domain:: wsme + +.. type:: MyType + + .. attribute:: test + + :type: int + +.. autotype:: wsme.sphinxext.SampleType + :members: diff --git a/doc/index.rst b/doc/index.rst index 147c801..39594c4 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -12,6 +12,7 @@ Contents types protocols integrate + document todo changes diff --git a/wsme/sphinxext.py b/wsme/sphinxext.py new file mode 100644 index 0000000..e453105 --- /dev/null +++ b/wsme/sphinxext.py @@ -0,0 +1,100 @@ +from sphinx.ext import autodoc +from sphinx.domains.python import PyClasslike, PyClassmember +from sphinx.domains import Domain, ObjType +from sphinx.util.docfields import Field, GroupedField, TypedField + +from sphinx.locale import l_, _ + +from docutils.parsers.rst import Directive + +import wsme + + +class SampleType(object): + """A Sample Type""" + + #: A Int + aint = int + + +class TypeDirective(PyClasslike): + pass + + +class AttributeDirective(PyClassmember): + doc_field_types = [ + Field('datatype', label=l_('Type'), has_arg=False, + names=('type', 'datatype')) + ] + + +class TypeDocumenter(autodoc.ClassDocumenter): + objtype = 'type' + directivetype = 'type' + domain = 'wsme' + + required_arguments = 1 + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + # we don't want to be automaticaly used + # TODO check if the member is registered a an exposed type + return False + + def format_name(self): + return self.object.__name__ + + def add_directive_header(self, sig): + super(TypeDocumenter, self).add_directive_header(sig) + # remove the :module: option that was added by ClassDocumenter + if ':module:' in self.directive.result[-1]: + self.directive.result.pop() + + def import_object(self): + if super(TypeDocumenter, self).import_object(): + wsme.types.register_type(self.object) + return True + else: + return False + + +class AttributeDocumenter(autodoc.AttributeDocumenter): + datatype = None + domain = 'wsme' + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + return isinstance(parent, TypeDocumenter) + + def import_object(self): + success = super(AttributeDocumenter, self).import_object() + if success: + self.datatype = self.object.datatype + return success + + def add_content(self, more_content, no_docstring=False): + self.add_line(u':type: %s' % self.datatype.__name__, '') + super(AttributeDocumenter, self).add_content( + more_content, no_docstring) + + def add_directive_header(self, sig): + super(AttributeDocumenter, self).add_directive_header(sig) + + +class WSMEDomain(Domain): + name = 'wsme' + + directives = { + 'type': TypeDirective, + 'attribute': AttributeDirective + } + + object_types = { + 'type': ObjType(l_('type'), 'type', 'obj') + } + + +def setup(app): + app.add_domain(WSMEDomain) + app.add_autodocumenter(TypeDocumenter) + app.add_autodocumenter(AttributeDocumenter)