Django templatetags上的Sphinx文档
我正在使用Sphinx和autodoc来记录我的Django项目 设计人员希望拥有关于项目中定义的所有模板标记的文档页面。当然,我可以通过手工枚举所有模板处理函数来创建这样一个页面,但我认为它不是干巴巴的,不是吗?事实上,模板标记处理函数都用Django templatetags上的Sphinx文档,django,python-sphinx,Django,Python Sphinx,我正在使用Sphinx和autodoc来记录我的Django项目 设计人员希望拥有关于项目中定义的所有模板标记的文档页面。当然,我可以通过手工枚举所有模板处理函数来创建这样一个页面,但我认为它不是干巴巴的,不是吗?事实上,模板标记处理函数都用@register.inclusion\u tagdecorator标记。因此,对于一些例行程序来说,将它们全部收集并放入文档中似乎是可能和自然的 过滤函数也是如此 我在谷歌上搜索过它,搜索过Django文档,但都是用血脉。我简直不敢相信这样一个自然的功能还
@register.inclusion\u tag
decorator标记。因此,对于一些例行程序来说,将它们全部收集并放入文档中似乎是可能和自然的
过滤函数也是如此
我在谷歌上搜索过它,搜索过Django文档,但都是用血脉。我简直不敢相信这样一个自然的功能还没有被人实现。我解决了这个问题,并想与大家分享我的代码片段,以防它们对别人有用 片段1。简单文档记录员
import os
os.environ['DJANGO_SETTINGS_MODULE'] = 'project.settings'
from django.template import get_library
def show_help(libname):
lib = get_library(libname)
print lib, ':'
for tag in lib.tags:
print tag
print lib.tags[tag].__doc__
if __name__ == '__main__':
show_help('lib.templatetags.bfmarkup')
在运行此脚本之前,您应该设置PYTHONPATH环境变量。我并没有就此停止,而是实现了Sphinx autodoc扩展 片段2。Sphinx autodoc扩展
"""
Extension of Sphinx autodoc for Django template tag libraries.
Usage:
.. autotaglib:: some.module.templatetags.mod
(options)
Most of the `module` autodoc directive flags are supported by `autotaglib`.
Andrew "Hatter" Ponomarev, 2010
"""
from sphinx.ext.autodoc import ModuleDocumenter, members_option, members_set_option, bool_option, identity
from sphinx.util.inspect import safe_getattr
from django.template import get_library, InvalidTemplateLibrary
class TaglibDocumenter(ModuleDocumenter):
"""
Specialized Documenter subclass for Django taglibs.
"""
objtype = 'taglib'
directivetype = 'module'
content_indent = u''
option_spec = {
'members': members_option, 'undoc-members': bool_option,
'noindex': bool_option,
'synopsis': identity,
'platform': identity, 'deprecated': bool_option,
'member-order': identity, 'exclude-members': members_set_option,
}
@classmethod
def can_document_member(cls, member, membername, isattr, parent):
# don't document submodules automatically
return False
def import_object(self):
"""
Import the taglibrary.
Returns True if successful, False if an error occurred.
"""
# do an ordinary module import
if not super(ModuleDocumenter, self).import_object():
return False
try:
# ask Django if specified module is a template tags library
# and - if it is so - get and save Library instance
self.taglib = get_library(self.object.__name__)
return True
except InvalidTemplateLibrary, e:
self.taglib = None
self.directive.warn(unicode(e))
return False
def get_object_members(self, want_all):
"""
Decide what members of current object must be autodocumented.
Return `(members_check_module, members)` where `members` is a
list of `(membername, member)` pairs of the members of *self.object*.
If *want_all* is True, return all members. Else, only return those
members given by *self.options.members* (which may also be none).
"""
if want_all:
return True, self.taglib.tags.items()
else:
memberlist = self.options.members or []
ret = []
for mname in memberlist:
if mname in taglib.tags:
ret.append((mname, self.taglib.tags[mname]))
else:
self.directive.warn(
'missing templatetag mentioned in :members: '
'module %s, templatetag %s' % (
safe_getattr(self.object, '__name__', '???'), mname))
return False, ret
def setup(app):
app.add_autodocumenter(TaglibDocumenter)
此扩展定义了Sphinx指令autotaglib
,其行为与automodule非常相似,但仅枚举标签实现函数
例如:
.. autotaglib:: lib.templatetags.bfmarkup
:members:
:undoc-members:
:noindex:
作为记录,Django有一个自动文档系统(将
Django.contrib.admindocs
添加到您的安装的应用程序中)
这将为您提供管理中的额外视图(通常位于/admin/docs/
),这些视图表示您的模型、视图(基于URL)、模板标记和模板过滤器
有关这方面的更多文档,请参阅
您可以查看该代码以将其包含在文档中,也可以查看Django文档的链接。因此,使用该代码而不是的好处是什么。。automodule::
是否可以将非模板标记类和函数的文档移到页面底部?我必须修复import\u object()
以使用self.taglib=get\u库(self.object.\uu名称\uuuu.split('.',-1))
来实现这一功能。