Django templatetags上的獅身人面像文檔

Question

我使用Sphinx和autodoc來記錄我的Django項目。

設計人員想要擁有關於項目中定義的所有模板標籤的文檔頁面。當然，我可以通過手工列舉所有模板處理函數來製作這樣的頁面，但我認爲它不是乾的，不是嗎？實際上，模板標籤處理函數全部用@register.inclusion_tag裝飾器標記。因此，對於一些例行程序來說，將它們全部收集並放入文檔似乎是可能的和自然的。

與過濾功能相同。

我已經使用它，搜索Django文檔，但在靜脈。我幾乎不能相信這樣的自然功能還沒有被某個人實現。

謝謝你的任何提示。

Answer 1

對於記錄，Django的具有自動文檔系統（添加django.contrib.admindocs到您INSTALLED_APPS）。

這會在管理員（通常在/admin/docs/）爲您提供代表您的模型，視圖（基於URL），模板標記和模板過濾器的額外視圖。

關於此問題的更多文檔可在admindocs section中找到。

您可以查看該代碼，以將其包含在您的文檔中或在Django文檔的extensions中。

Answer 2

我解決了這個問題，並希望分享我的片段 - 以防他們對別人有用。

片段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環境變量之前。

Answer 3

我沒有停止在這一點上，並實現了一個獅身人面像autodoc擴展。

片段2.斯芬克斯車博士延伸

""" 
    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) 

本擴展定義斯芬克斯指令autotaglib它的行爲就像automodule，但是僅列舉標籤實現功能。

實施例：

.. autotaglib:: lib.templatetags.bfmarkup 
    :members: 
    :undoc-members: 
    :noindex: