Add some docs using sphinx autodoc
This commit is contained in:
Valentin Samir
@ -50,6 +50,7 @@ clean:
|
||||
|
||||
.PHONY: html
|
||||
html:
|
||||
wget https://docs.djangoproject.com/en/1.9/_objects -O django.inv
|
||||
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
||||
|
||||
321
docs/_ext/djangodocs.py
Normal file
321
docs/_ext/djangodocs.py
Normal file
@ -0,0 +1,321 @@
|
||||
"""
|
||||
Sphinx plugins for Django documentation.
|
||||
"""
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
|
||||
from docutils import nodes
|
||||
from docutils.parsers.rst import directives
|
||||
from sphinx import addnodes
|
||||
from sphinx.builders.html import StandaloneHTMLBuilder
|
||||
from sphinx.domains.std import Cmdoption
|
||||
from sphinx.util.compat import Directive
|
||||
from sphinx.util.console import bold
|
||||
from sphinx.util.nodes import set_source_info
|
||||
from sphinx.writers.html import SmartyPantsHTMLTranslator
|
||||
|
||||
# RE for option descriptions without a '--' prefix
|
||||
simple_option_desc_re = re.compile(
|
||||
r'([-_a-zA-Z0-9]+)(\s*.*?)(?=,\s+(?:/|-|--)|$)')
|
||||
|
||||
|
||||
def setup(app):
|
||||
app.add_crossref_type(
|
||||
directivename="setting",
|
||||
rolename="setting",
|
||||
indextemplate="pair: %s; setting",
|
||||
)
|
||||
app.add_crossref_type(
|
||||
directivename="templatetag",
|
||||
rolename="ttag",
|
||||
indextemplate="pair: %s; template tag"
|
||||
)
|
||||
app.add_crossref_type(
|
||||
directivename="templatefilter",
|
||||
rolename="tfilter",
|
||||
indextemplate="pair: %s; template filter"
|
||||
)
|
||||
app.add_crossref_type(
|
||||
directivename="fieldlookup",
|
||||
rolename="lookup",
|
||||
indextemplate="pair: %s; field lookup type",
|
||||
)
|
||||
app.add_description_unit(
|
||||
directivename="django-admin",
|
||||
rolename="djadmin",
|
||||
indextemplate="pair: %s; django-admin command",
|
||||
parse_node=parse_django_admin_node,
|
||||
)
|
||||
app.add_directive('django-admin-option', Cmdoption)
|
||||
app.add_config_value('django_next_version', '0.0', True)
|
||||
app.add_directive('versionadded', VersionDirective)
|
||||
app.add_directive('versionchanged', VersionDirective)
|
||||
app.add_builder(DjangoStandaloneHTMLBuilder)
|
||||
|
||||
# register the snippet directive
|
||||
app.add_directive('snippet', SnippetWithFilename)
|
||||
# register a node for snippet directive so that the xml parser
|
||||
# knows how to handle the enter/exit parsing event
|
||||
app.add_node(snippet_with_filename,
|
||||
html=(visit_snippet, depart_snippet_literal),
|
||||
latex=(visit_snippet_latex, depart_snippet_latex),
|
||||
man=(visit_snippet_literal, depart_snippet_literal),
|
||||
text=(visit_snippet_literal, depart_snippet_literal),
|
||||
texinfo=(visit_snippet_literal, depart_snippet_literal))
|
||||
return {'parallel_read_safe': True}
|
||||
|
||||
|
||||
class snippet_with_filename(nodes.literal_block):
|
||||
"""
|
||||
Subclass the literal_block to override the visit/depart event handlers
|
||||
"""
|
||||
pass
|
||||
|
||||
|
||||
def visit_snippet_literal(self, node):
|
||||
"""
|
||||
default literal block handler
|
||||
"""
|
||||
self.visit_literal_block(node)
|
||||
|
||||
|
||||
def depart_snippet_literal(self, node):
|
||||
"""
|
||||
default literal block handler
|
||||
"""
|
||||
self.depart_literal_block(node)
|
||||
|
||||
|
||||
def visit_snippet(self, node):
|
||||
"""
|
||||
HTML document generator visit handler
|
||||
"""
|
||||
lang = self.highlightlang
|
||||
linenos = node.rawsource.count('\n') >= self.highlightlinenothreshold - 1
|
||||
fname = node['filename']
|
||||
highlight_args = node.get('highlight_args', {})
|
||||
if 'language' in node:
|
||||
# code-block directives
|
||||
lang = node['language']
|
||||
highlight_args['force'] = True
|
||||
if 'linenos' in node:
|
||||
linenos = node['linenos']
|
||||
|
||||
def warner(msg):
|
||||
self.builder.warn(msg, (self.builder.current_docname, node.line))
|
||||
|
||||
highlighted = self.highlighter.highlight_block(node.rawsource, lang,
|
||||
warn=warner,
|
||||
linenos=linenos,
|
||||
**highlight_args)
|
||||
starttag = self.starttag(node, 'div', suffix='',
|
||||
CLASS='highlight-%s snippet' % lang)
|
||||
self.body.append(starttag)
|
||||
self.body.append('<div class="snippet-filename">%s</div>\n''' % (fname,))
|
||||
self.body.append(highlighted)
|
||||
self.body.append('</div>\n')
|
||||
raise nodes.SkipNode
|
||||
|
||||
|
||||
def visit_snippet_latex(self, node):
|
||||
"""
|
||||
Latex document generator visit handler
|
||||
"""
|
||||
code = node.rawsource.rstrip('\n')
|
||||
|
||||
lang = self.hlsettingstack[-1][0]
|
||||
linenos = code.count('\n') >= self.hlsettingstack[-1][1] - 1
|
||||
fname = node['filename']
|
||||
highlight_args = node.get('highlight_args', {})
|
||||
if 'language' in node:
|
||||
# code-block directives
|
||||
lang = node['language']
|
||||
highlight_args['force'] = True
|
||||
if 'linenos' in node:
|
||||
linenos = node['linenos']
|
||||
|
||||
def warner(msg):
|
||||
self.builder.warn(msg, (self.curfilestack[-1], node.line))
|
||||
|
||||
hlcode = self.highlighter.highlight_block(code, lang, warn=warner,
|
||||
linenos=linenos,
|
||||
**highlight_args)
|
||||
|
||||
self.body.append(
|
||||
'\n{\\colorbox[rgb]{0.9,0.9,0.9}'
|
||||
'{\\makebox[\\textwidth][l]'
|
||||
'{\\small\\texttt{%s}}}}\n' % (
|
||||
# Some filenames have '_', which is special in latex.
|
||||
fname.replace('_', r'\_'),
|
||||
)
|
||||
)
|
||||
|
||||
if self.table:
|
||||
hlcode = hlcode.replace('\\begin{Verbatim}',
|
||||
'\\begin{OriginalVerbatim}')
|
||||
self.table.has_problematic = True
|
||||
self.table.has_verbatim = True
|
||||
|
||||
hlcode = hlcode.rstrip()[:-14] # strip \end{Verbatim}
|
||||
hlcode = hlcode.rstrip() + '\n'
|
||||
self.body.append('\n' + hlcode + '\\end{%sVerbatim}\n' %
|
||||
(self.table and 'Original' or ''))
|
||||
|
||||
# Prevent rawsource from appearing in output a second time.
|
||||
raise nodes.SkipNode
|
||||
|
||||
|
||||
def depart_snippet_latex(self, node):
|
||||
"""
|
||||
Latex document generator depart handler.
|
||||
"""
|
||||
pass
|
||||
|
||||
|
||||
class SnippetWithFilename(Directive):
|
||||
"""
|
||||
The 'snippet' directive that allows to add the filename (optional)
|
||||
of a code snippet in the document. This is modeled after CodeBlock.
|
||||
"""
|
||||
has_content = True
|
||||
optional_arguments = 1
|
||||
option_spec = {'filename': directives.unchanged_required}
|
||||
|
||||
def run(self):
|
||||
code = '\n'.join(self.content)
|
||||
|
||||
literal = snippet_with_filename(code, code)
|
||||
if self.arguments:
|
||||
literal['language'] = self.arguments[0]
|
||||
literal['filename'] = self.options['filename']
|
||||
set_source_info(self, literal)
|
||||
return [literal]
|
||||
|
||||
|
||||
class VersionDirective(Directive):
|
||||
has_content = True
|
||||
required_arguments = 1
|
||||
optional_arguments = 1
|
||||
final_argument_whitespace = True
|
||||
option_spec = {}
|
||||
|
||||
def run(self):
|
||||
if len(self.arguments) > 1:
|
||||
msg = """Only one argument accepted for directive '{directive_name}::'.
|
||||
Comments should be provided as content,
|
||||
not as an extra argument.""".format(directive_name=self.name)
|
||||
raise self.error(msg)
|
||||
|
||||
env = self.state.document.settings.env
|
||||
ret = []
|
||||
node = addnodes.versionmodified()
|
||||
ret.append(node)
|
||||
|
||||
if self.arguments[0] == env.config.django_next_version:
|
||||
node['version'] = "Development version"
|
||||
else:
|
||||
node['version'] = self.arguments[0]
|
||||
|
||||
node['type'] = self.name
|
||||
if self.content:
|
||||
self.state.nested_parse(self.content, self.content_offset, node)
|
||||
env.note_versionchange(node['type'], node['version'], node, self.lineno)
|
||||
return ret
|
||||
|
||||
|
||||
class DjangoHTMLTranslator(SmartyPantsHTMLTranslator):
|
||||
"""
|
||||
Django-specific reST to HTML tweaks.
|
||||
"""
|
||||
|
||||
# Don't use border=1, which docutils does by default.
|
||||
def visit_table(self, node):
|
||||
self.context.append(self.compact_p)
|
||||
self.compact_p = True
|
||||
self._table_row_index = 0 # Needed by Sphinx
|
||||
self.body.append(self.starttag(node, 'table', CLASS='docutils'))
|
||||
|
||||
def depart_table(self, node):
|
||||
self.compact_p = self.context.pop()
|
||||
self.body.append('</table>\n')
|
||||
|
||||
def visit_desc_parameterlist(self, node):
|
||||
self.body.append('(') # by default sphinx puts <big> around the "("
|
||||
self.first_param = 1
|
||||
self.optional_param_level = 0
|
||||
self.param_separator = node.child_text_separator
|
||||
self.required_params_left = sum([isinstance(c, addnodes.desc_parameter)
|
||||
for c in node.children])
|
||||
|
||||
def depart_desc_parameterlist(self, node):
|
||||
self.body.append(')')
|
||||
|
||||
#
|
||||
# Turn the "new in version" stuff (versionadded/versionchanged) into a
|
||||
# better callout -- the Sphinx default is just a little span,
|
||||
# which is a bit less obvious that I'd like.
|
||||
#
|
||||
# FIXME: these messages are all hardcoded in English. We need to change
|
||||
# that to accommodate other language docs, but I can't work out how to make
|
||||
# that work.
|
||||
#
|
||||
version_text = {
|
||||
'versionchanged': 'Changed in Django %s',
|
||||
'versionadded': 'New in Django %s',
|
||||
}
|
||||
|
||||
def visit_versionmodified(self, node):
|
||||
self.body.append(
|
||||
self.starttag(node, 'div', CLASS=node['type'])
|
||||
)
|
||||
version_text = self.version_text.get(node['type'])
|
||||
if version_text:
|
||||
title = "%s%s" % (
|
||||
version_text % node['version'],
|
||||
":" if len(node) else "."
|
||||
)
|
||||
self.body.append('<span class="title">%s</span> ' % title)
|
||||
|
||||
def depart_versionmodified(self, node):
|
||||
self.body.append("</div>\n")
|
||||
|
||||
# Give each section a unique ID -- nice for custom CSS hooks
|
||||
def visit_section(self, node):
|
||||
old_ids = node.get('ids', [])
|
||||
node['ids'] = ['s-' + i for i in old_ids]
|
||||
node['ids'].extend(old_ids)
|
||||
SmartyPantsHTMLTranslator.visit_section(self, node)
|
||||
node['ids'] = old_ids
|
||||
|
||||
|
||||
def parse_django_admin_node(env, sig, signode):
|
||||
command = sig.split(' ')[0]
|
||||
env.ref_context['std:program'] = command
|
||||
title = "django-admin %s" % sig
|
||||
signode += addnodes.desc_name(title, title)
|
||||
return command
|
||||
|
||||
|
||||
class DjangoStandaloneHTMLBuilder(StandaloneHTMLBuilder):
|
||||
"""
|
||||
Subclass to add some extra things we need.
|
||||
"""
|
||||
|
||||
name = 'djangohtml'
|
||||
|
||||
def finish(self):
|
||||
super(DjangoStandaloneHTMLBuilder, self).finish()
|
||||
self.info(bold("writing templatebuiltins.js..."))
|
||||
xrefs = self.env.domaindata["std"]["objects"]
|
||||
templatebuiltins = {
|
||||
"ttags": [n for ((t, n), (l, a)) in xrefs.items()
|
||||
if t == "templatetag" and l == "ref/templates/builtins"],
|
||||
"tfilters": [n for ((t, n), (l, a)) in xrefs.items()
|
||||
if t == "templatefilter" and l == "ref/templates/builtins"],
|
||||
}
|
||||
outfilename = os.path.join(self.outdir, "templatebuiltins.js")
|
||||
with open(outfilename, 'w') as fp:
|
||||
fp.write('var django_template_builtins = ')
|
||||
json.dump(templatebuiltins, fp)
|
||||
fp.write(';\n')
|
||||
12
docs/conf.py
12
docs/conf.py
@ -20,6 +20,7 @@ import os
|
||||
import sys
|
||||
sys.path.insert(0, os.path.abspath('.'))
|
||||
sys.path.append(os.path.abspath('..'))
|
||||
sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "_ext")))
|
||||
|
||||
SETUP = os.path.abspath('../setup.py')
|
||||
|
||||
@ -37,6 +38,7 @@ django.setup()
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = [
|
||||
'djangodocs',
|
||||
'sphinx.ext.autodoc',
|
||||
'sphinx.ext.doctest',
|
||||
'sphinx.ext.intersphinx',
|
||||
@ -346,11 +348,11 @@ texinfo_documents = [
|
||||
# texinfo_no_detailmenu = False
|
||||
|
||||
# Example configuration for intersphinx: refer to the Python standard library.
|
||||
intersphinx_mapping = {'https://docs.python.org/': None}
|
||||
intersphinx_mapping = {
|
||||
"python": ('https://docs.python.org/', None),
|
||||
"django": ('https://docs.djangoproject.com/en/1.9/', 'django.inv'),
|
||||
}
|
||||
|
||||
autodoc_member_order = 'bysource'
|
||||
|
||||
def setup(app):
|
||||
from django_sphinx import process_docstring
|
||||
# Register the docstring processor with sphinx
|
||||
app.connect('autodoc-process-docstring', process_docstring)
|
||||
locale_dirs = ['../test_venv/lib/python2.7/site-packages/django/conf/locale/']
|
||||
|
||||
@ -1,41 +0,0 @@
|
||||
import inspect
|
||||
from django.utils.html import strip_tags
|
||||
from django.utils.encoding import force_unicode
|
||||
|
||||
def process_docstring(app, what, name, obj, options, lines):
|
||||
# This causes import errors if left outside the function
|
||||
from django.db import models
|
||||
|
||||
# Only look at objects that inherit from Django's base model class
|
||||
if inspect.isclass(obj) and issubclass(obj, models.Model):
|
||||
# Grab the field list from the meta class
|
||||
fields = obj._meta.fields
|
||||
|
||||
for field in fields:
|
||||
# Decode and strip any html out of the field's help text
|
||||
help_text = strip_tags(force_unicode(field.help_text))
|
||||
|
||||
# Decode and capitalize the verbose name, for use if there isn't
|
||||
# any help text
|
||||
verbose_name = force_unicode(field.verbose_name).capitalize()
|
||||
|
||||
if help_text:
|
||||
# Add the model field to the end of the docstring as a param
|
||||
# using the help text as the description
|
||||
lines.append(u':param %s: %s' % (field.attname, help_text))
|
||||
else:
|
||||
# Add the model field to the end of the docstring as a param
|
||||
# using the verbose name as the description
|
||||
lines.append(u':param %s: %s' % (field.attname, verbose_name))
|
||||
|
||||
# Add the field's type to the docstring
|
||||
if isinstance(field, models.ForeignKey):
|
||||
to = field.rel.to
|
||||
lines.append(u':type %s: %s to :class:`~%s.%s`' % (field.attname, type(field).__name__, to.__module__, to.__name__))
|
||||
|
||||
else:
|
||||
lines.append(u':type %s: %s' % (field.attname, type(field).__name__))
|
||||
|
||||
# Return the extended docstring
|
||||
return lines
|
||||
|
||||
@ -4,4 +4,4 @@ cas_server.admin module
|
||||
.. automodule:: cas_server.admin
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
@ -4,4 +4,3 @@ cas_server.apps module
|
||||
.. automodule:: cas_server.apps
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
@ -3,5 +3,3 @@ cas_server.forms module
|
||||
|
||||
.. automodule:: cas_server.forms
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
@ -4,4 +4,3 @@ cas_server.models module
|
||||
.. automodule:: cas_server.models
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
@ -1,7 +0,0 @@
|
||||
cas_server.urls module
|
||||
======================
|
||||
|
||||
.. automodule:: cas_server.urls
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
Reference in New Issue
Block a user