django 1.8 官方文档翻译:7-3 Django管理文档生成器
Django管理文档生成器
Django的admindocs
应用从模型、视图、模板标签以及模板过滤器中,为任何INSTALLED_APPS
中的应用获取文档。并且让文档可以在Django admin
中使用。
在某种程度上,你可以使用admindocs
来快为你自己的代码生成文档。这个应用的功能十分有限,然而它主要用于文档模板、模板标签和过滤器。例如,需要参数的模型方法在文档中会有意地忽略,因为它们不能从模板中调用。这个应用仍旧有用,因为它并不需要你编写任何额外的文档(除了docstrings
),并且在 Django admin
中使用很方便。
概览
要启用admindocs
,你需要执行以下步骤:
- 向
INSTALLED_APPS
添加django.contrib.admindocs
。 - 向你的
urlpatterns
添加(r'^admin/doc/'
,include('django.contrib.admindocs.urls')
)。 确保它在r'^admin/'
这一项 之前包含,以便/admin/doc/
的请求不会被后面的项目处理。 - 安装
docutils
Python 模块 (http://docutils.sf.net/)。 - 可选的: 使用
admindocs
的书签功能需要安装django.contrib.admindocs.middleware.XViewMiddleware
。
一旦完成这些步骤,你可以开始通过你的admin
接口和点击在页面右上方的“Documentation”链接来浏览文档。
文档助手
下列特定的标记可以用于你的docstrings
,来轻易创建到其他组件的超链接:
Django Component | reStructuredText roles |
---|---|
Models | :model:`app_label.ModelName` |
Views | :view:`app_label.view_name` |
Template tags | :tag:`tagname` |
Template filters | :filter:`filtername` |
Templates | :template:`path/to/template.html` |
模型参考
admindocs
页面的models
部分描述了系统中每个模型,以及所有可用的字段和方法(不带任何参数)。虽然模型的属性没有任何参数,但他们没有列出。和其它模型的关联以超链接形式出现。描述由字段上的help_text
属性,或者从模型方法的docstrings
导出。
带有有用文档的模型看起来像是这样:
class BlogEntry(models.Model):"""Stores a single blog entry, related to :model:`blog.Blog` and:model:`auth.User`."""slug = models.SlugField(help_text="A short label, generally used in URLs.")author = models.ForeignKey(User)blog = models.ForeignKey(Blog)...def publish(self):"""Makes the blog entry live on the site."""...
视图参考
你站点中的每个URL都在·页面中有一个单独的记录,点击提供的URL会向你展示相应的视图。有一些有用的东西,你可以在你的视图函数的·中记录:
- 视图所做工作的一个简短的描述。
- 上下文,或者是视图的模板中可用变量的列表。
- 用于当前视图的模板的名称。
例如:
from django.shortcuts import renderfrom myapp.models import MyModeldef my_view(request, slug):"""Display an individual :model:`myapp.MyModel`.**Context**``mymodel``An instance of :model:`myapp.MyModel`.**Template:**:template:`myapp/my_template.html`"""context = {'mymodel': MyModel.objects.get(slug=slug)}return render(request, 'myapp/my_template.html', context)
模板标签和过滤器参考
admindocs
的tags
和filters
部分描述了Django自带的所有标签和过滤器(事实上,内建的标签参考 和 内建的过滤器参考文档直接来自于那些页面)。你创建的,或者由三方应用添加的任何标签或者过滤器,也会在这一部分中展示。
模板参考
虽然admindocs
并不包含一个地方来保存模板,但如果你在结果页面中使用:template:`path/to/template.html`
语法,会使用Django的模板加载器来验证该模板的路径。这是一个非常便捷的方法,来检查是否存在特定的模板,以及展示模板在文件系统的何处存放。
包含的书签
admindocs
页面上有一些很有用的书签:
Documentation for this page
Jumps you from any page to the documentation for the view that generates that page.
Show object ID
Shows the content-type and unique ID for pages that represent a single object.
Edit this object
Jumps to the admin page for pages that represent a single object.
为使用这些书签,你需要用带有is_staff
设置为 True
的User
登录Django admin
,或者安装了XViewMiddleware
并且你通过 INTERNAL_IPS
中的IP地址访问站点。
译者:Django 文档协作翻译小组,原文:Admin documentation generator。
本文以 CC BY-NC-SA 3.0 协议发布,转载请保留作者署名和文章出处。
Django 文档协作翻译小组人手紧缺,有兴趣的朋友可以加入我们,完全公益性质。交流群:467338606。
django 1.8 官方文档翻译:7-3 Django管理文档生成器相关推荐
- django 1.8 官方文档翻译:6-3 Django异常
Django异常 DJango会抛出一些它自己的异常,以及Python的标准异常. Django核心异常 Django核心异常类定义在django.core.exceptions中. ObjectDo ...
- django 1.8 官方文档翻译:4-2-1 Django模版语言
Django模版语言 本文将介绍Django模版系统的语法.如果您需要更多该系统如何工作的技术细节,以及希望扩展它,请浏览 The Django template language: for Pyth ...
- django 1.8 官方文档翻译:13-1-3 密码管理
Django中的密码管理 密码管理在非必要情况下一般不会重新发明,Django致力于提供一套安全.灵活的工具集来管理用户密码.本文档描述Django存储密码和hash存储方法配置的方式,以及使用has ...
- django 1.8 官方文档翻译:6-5-1 Django中的测试
Django中的测试 自动化测试对于现代web开发者来说,是非常实用的除错工具.你可以使用一系列测试– 测试套件 – 来解决或者避免大量问题: 当你编写新代码的时候,你可以使用测试来验证你的代码是否像 ...
- django 1.8 官方文档翻译: 13-1-1 Django 中的用户认证
Django 中的用户认证 Django从开始就带有一个用户认证系统.它处理用户账号.组.权限以及基于cookie的用户会话.本节文档解释默认的实现如何直接使用,以及如何扩展和定制它以适合你项目的需要 ...
- django 1.8 官方文档翻译: 1-1-1 Django初探
Django 初探 由于Django是在一个快节奏的新闻编辑室环境下开发出来的,因此它被设计成让普通的网站开发工作简单而快 捷.以下简单介绍了如何用 Django 编写一个数据库驱动的Web应用程序. ...
- django 1.8 官方文档翻译: 6-1-1 Django 的设置
Django 的设置 Django 的设置文件包含你安装的Django 的所有配置.这页文档解释设置是如何工作以及有哪些设置. 基础 设置文件只是一个Python 模块,带有模块级别的变量. 下面是一 ...
- django 1.8 官方文档翻译: 3-1-3 Django 的快捷函数
Django 的快捷函数 django.shortcuts 收集了"跨越" 多层MVC 的辅助函数和类. 换句话讲,这些函数/类为了方便,引入了可控的耦合. render rend ...
- django 1.8 官方文档翻译:使用Django认证系统
使用Django认证系统 这篇文档解释默认配置下Django认证系统的使用.这些配置已经逐步可以满足大部分常见项目对的需要,可以处理范围非常广泛的任务,且具有一套细致的密码和权限实现.对于需要与默认配 ...
最新文章
- 转:PHP Liunx 服务安全防范方案
- datagridview新增列在最后_数说|科创板2020:募资额2200+亿超主板列A股第一,科技“千元股”、“市值王”长成...
- IOS客户端rtmp
- delete hive_「挑战30万年薪」 Hive语句详解之从SQL到HQL的应转习惯
- linux jsp mysql数据库,Linux JSP连接MySQL数据库.pdf
- LeetCode 147. Insertion Sort List 链表插入排序 C++/Java
- 夫妻两人同一个银行各自存50万,银行破产了该赔多少?
- c语言与python通信_C和Python – 与套接字通信
- python unpack_python中struct.pack()函数和struct.unpack()函数
- Leetcode重点题
- 微信公众平台测试账号申请地址
- python欢迎你、某某某同学_python __xx__的定义和用处
- Cannot find current proxy: Set ‘exposeProxy‘ property on Advised to ‘true‘ to make it available.
- Win10如何用命令打开控制面板
- AI Text Classifier,OpenAI自家产品,我检测我自己
- 数据库标准语言SQL(六)——单表查询(二)
- ABAP 金额小写转大写
- 视觉SLAM面试题汇总(三)
- mysql数据表添加列_如何将列添加到MySQL表
- 循环中continue用法
热门文章
- 24小时学会python_零基础python24小时极速入门学习
- STM32编码器的学习笔记
- 【嵌入式Linux】嵌入式Linux驱动开发基础知识之LED模板驱动程序的改造:设备树
- Linux下的虚拟Bridge实现
- linux下ip层的一些概念
- ROS:定制自己的消息类型msg
- gis地图和普通地图的区别_GIS之如何添加WMTS地图
- 英伟达显卡不同架构_英伟达GeForce RTX 3070 Ti与RTX 3070显卡规格曝光
- c语言ics什么意思,[转载]C网来话筛选(ICS)业务及实现
- php显示当前访问人数,PHP与jquery实时显示网站在线人数实例详解