Документация Sphinx по шаблонам Django - PullRequest
Новая
       10

Документация Sphinx по шаблонам Django

3 голосов
/ 10 октября 2010

Я использую Sphinx с autodoc для документирования своего проекта Django.

Дизайнеры хотят иметь страницы документации по всем тегам шаблонов, которые определены в проекте.Конечно, я могу создать такую ​​страницу, перечислив вручную все функции обработки шаблонов, но я думаю, что это не СУХОЙ, не так ли?Фактически, все функции обработки тегов шаблонов помечены @register.inclusion_tag декоратором.Таким образом, кажется вполне возможным и естественным для некоторой подпрограммы собрать их все и поместить в документацию.

То же самое с функциями фильтра.

Я гуглял, искал документацию Django, но в вене,Я с трудом могу поверить, что такая естественная функциональность не была реализована кем-то.

Спасибо за любые подсказки.

Ответы [ 3 ]

3 голосов
/ 13 октября 2010

На этом я не остановился и реализовал расширение автодок Sphinx.

Фрагмент 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, которая ведет себя подобно автомодулю, но перечисляет только функции реализации тегов.

Пример: 

.. autotaglib:: lib.templatetags.bfmarkup
   :members:
   :undoc-members:
   :noindex:
1 голос
/ 08 июня 2011

Для справки, в Django есть автоматическая система документирования (добавьте django.contrib.admindocs к вашему INSTALLED_APPS).

Это даст вам дополнительные представления в администраторе (обычно на /admin/docs/), которые представляют ваши модели, представления (на основе URL), теги шаблонов и фильтры шаблонов.

Дополнительную документацию по этому вопросу можно найти в разделе admindocs .

Вы можете взглянуть на этот код, чтобы включить его в свою документацию или в расширения для документации Django.

0 голосов
/ 13 октября 2010

Я решил проблему и хотел бы поделиться своими фрагментами - на случай, если они кому-нибудь пригодятся.

Фрагмент 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.

...