├── .gitignore ├── Makefile ├── conf.py ├── contents.rst ├── make.bat └── readme.rst /.gitignore: -------------------------------------------------------------------------------- 1 | _build/ 2 | .svn/ -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | PAPER = 8 | BUILDDIR = _build 9 | 10 | # Internal variables. 11 | PAPEROPT_a4 = -D latex_paper_size=a4 12 | PAPEROPT_letter = -D latex_paper_size=letter 13 | ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 14 | 15 | .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest 16 | 17 | help: 18 | @echo "Please use \`make ' where is one of" 19 | @echo " html to make standalone HTML files" 20 | @echo " dirhtml to make HTML files named index.html in directories" 21 | @echo " singlehtml to make a single large HTML file" 22 | @echo " pickle to make pickle files" 23 | @echo " json to make JSON files" 24 | @echo " htmlhelp to make HTML files and a HTML help project" 25 | @echo " qthelp to make HTML files and a qthelp project" 26 | @echo " devhelp to make HTML files and a Devhelp project" 27 | @echo " epub to make an epub" 28 | @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 29 | @echo " latexpdf to make LaTeX files and run them through pdflatex" 30 | @echo " text to make text files" 31 | @echo " man to make manual pages" 32 | @echo " changes to make an overview of all changed/added/deprecated items" 33 | @echo " linkcheck to check all external links for integrity" 34 | @echo " doctest to run all doctests embedded in the documentation (if enabled)" 35 | 36 | clean: 37 | -rm -rf $(BUILDDIR)/* 38 | 39 | html: 40 | $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 41 | @echo 42 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 43 | 44 | dirhtml: 45 | $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 46 | @echo 47 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." 48 | 49 | singlehtml: 50 | $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 51 | @echo 52 | @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." 53 | 54 | pickle: 55 | $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 56 | @echo 57 | @echo "Build finished; now you can process the pickle files." 58 | 59 | json: 60 | $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json 61 | @echo 62 | @echo "Build finished; now you can process the JSON files." 63 | 64 | htmlhelp: 65 | $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 66 | @echo 67 | @echo "Build finished; now you can run HTML Help Workshop with the" \ 68 | ".hhp project file in $(BUILDDIR)/htmlhelp." 69 | 70 | qthelp: 71 | $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 72 | @echo 73 | @echo "Build finished; now you can run "qcollectiongenerator" with the" \ 74 | ".qhcp project file in $(BUILDDIR)/qthelp, like this:" 75 | @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/django-best-practices.qhcp" 76 | @echo "To view the help file:" 77 | @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/django-best-practices.qhc" 78 | 79 | devhelp: 80 | $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 81 | @echo 82 | @echo "Build finished." 83 | @echo "To view the help file:" 84 | @echo "# mkdir -p $$HOME/.local/share/devhelp/django-best-practices" 85 | @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/django-best-practices" 86 | @echo "# devhelp" 87 | 88 | epub: 89 | $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub 90 | @echo 91 | @echo "Build finished. The epub file is in $(BUILDDIR)/epub." 92 | 93 | latex: 94 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 95 | @echo 96 | @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." 97 | @echo "Run \`make' in that directory to run these through (pdf)latex" \ 98 | "(use \`make latexpdf' here to do that automatically)." 99 | 100 | latexpdf: 101 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 102 | @echo "Running LaTeX files through pdflatex..." 103 | make -C $(BUILDDIR)/latex all-pdf 104 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 105 | 106 | text: 107 | $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text 108 | @echo 109 | @echo "Build finished. The text files are in $(BUILDDIR)/text." 110 | 111 | man: 112 | $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man 113 | @echo 114 | @echo "Build finished. The manual pages are in $(BUILDDIR)/man." 115 | 116 | changes: 117 | $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes 118 | @echo 119 | @echo "The overview file is in $(BUILDDIR)/changes." 120 | 121 | linkcheck: 122 | $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 123 | @echo 124 | @echo "Link check complete; look for any errors in the above output " \ 125 | "or in $(BUILDDIR)/linkcheck/output.txt." 126 | 127 | doctest: 128 | $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 129 | @echo "Testing of doctests in the sources finished, look at the " \ 130 | "results in $(BUILDDIR)/doctest/output.txt." 131 | -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | 3 | 4 | 5 | import sys, os 6 | project = u'Django 最佳实践' 7 | copyright = u'' 8 | version = u'' 9 | release = u'' 10 | 11 | source_suffix = '.rst' 12 | master_doc = 'index' 13 | language = 'zh_CN' 14 | exclude_patterns = ['_build'] 15 | extensions = ['sphinx.ext.pngmath'] 16 | pygments_style = 'sphinx' 17 | 18 | html_title = u'Django 最佳实践' 19 | html_theme = 'haiku' 20 | html_theme_path = ['../../../templates/sphinx', ] 21 | htmlhelp_basename = 'django-best-practices' 22 | html_add_permalinks = None 23 | 24 | file_insertion_enabled = False 25 | latex_documents = [ 26 | ('index', 'django-best-practices.tex', u'Django 最佳实践', 27 | u'', 'manual'), 28 | ] 29 | 30 | exclude_patterns = ['README.rst'] 31 | 32 | 33 | #Add sponsorship and project information to the template context. 34 | context = { 35 | 'MEDIA_URL': "/media/", 36 | 'slug': 'django-best-practices', 37 | 'name': u'Django 最佳实践', 38 | 'analytics_code': '', 39 | } 40 | 41 | html_context = context 42 | -------------------------------------------------------------------------------- /contents.rst: -------------------------------------------------------------------------------- 1 | .. 请确保至少包含基本的 `toctree` 指令. 2 | 3 | .. _contents: 4 | 5 | 内容目录 6 | ======== 7 | 8 | .. toctree:: 9 | 10 | index 11 | 12 | -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | REM Command file for Sphinx documentation 4 | 5 | if "%SPHINXBUILD%" == "" ( 6 | set SPHINXBUILD=sphinx-build 7 | ) 8 | set BUILDDIR=_build 9 | set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . 10 | if NOT "%PAPER%" == "" ( 11 | set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% 12 | ) 13 | 14 | if "%1" == "" goto help 15 | 16 | if "%1" == "help" ( 17 | :help 18 | echo.Please use `make ^` where ^ is one of 19 | echo. html to make standalone HTML files 20 | echo. dirhtml to make HTML files named index.html in directories 21 | echo. singlehtml to make a single large HTML file 22 | echo. pickle to make pickle files 23 | echo. json to make JSON files 24 | echo. htmlhelp to make HTML files and a HTML help project 25 | echo. qthelp to make HTML files and a qthelp project 26 | echo. devhelp to make HTML files and a Devhelp project 27 | echo. epub to make an epub 28 | echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter 29 | echo. text to make text files 30 | echo. man to make manual pages 31 | echo. changes to make an overview over all changed/added/deprecated items 32 | echo. linkcheck to check all external links for integrity 33 | echo. doctest to run all doctests embedded in the documentation if enabled 34 | goto end 35 | ) 36 | 37 | if "%1" == "clean" ( 38 | for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i 39 | del /q /s %BUILDDIR%\* 40 | goto end 41 | ) 42 | 43 | if "%1" == "html" ( 44 | %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html 45 | if errorlevel 1 exit /b 1 46 | echo. 47 | echo.Build finished. The HTML pages are in %BUILDDIR%/html. 48 | goto end 49 | ) 50 | 51 | if "%1" == "dirhtml" ( 52 | %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml 53 | if errorlevel 1 exit /b 1 54 | echo. 55 | echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. 56 | goto end 57 | ) 58 | 59 | if "%1" == "singlehtml" ( 60 | %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml 61 | if errorlevel 1 exit /b 1 62 | echo. 63 | echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. 64 | goto end 65 | ) 66 | 67 | if "%1" == "pickle" ( 68 | %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle 69 | if errorlevel 1 exit /b 1 70 | echo. 71 | echo.Build finished; now you can process the pickle files. 72 | goto end 73 | ) 74 | 75 | if "%1" == "json" ( 76 | %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json 77 | if errorlevel 1 exit /b 1 78 | echo. 79 | echo.Build finished; now you can process the JSON files. 80 | goto end 81 | ) 82 | 83 | if "%1" == "htmlhelp" ( 84 | %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp 85 | if errorlevel 1 exit /b 1 86 | echo. 87 | echo.Build finished; now you can run HTML Help Workshop with the ^ 88 | .hhp project file in %BUILDDIR%/htmlhelp. 89 | goto end 90 | ) 91 | 92 | if "%1" == "qthelp" ( 93 | %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp 94 | if errorlevel 1 exit /b 1 95 | echo. 96 | echo.Build finished; now you can run "qcollectiongenerator" with the ^ 97 | .qhcp project file in %BUILDDIR%/qthelp, like this: 98 | echo.^> qcollectiongenerator %BUILDDIR%\qthelp\django-best-practices.qhcp 99 | echo.To view the help file: 100 | echo.^> assistant -collectionFile %BUILDDIR%\qthelp\django-best-practices.ghc 101 | goto end 102 | ) 103 | 104 | if "%1" == "devhelp" ( 105 | %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp 106 | if errorlevel 1 exit /b 1 107 | echo. 108 | echo.Build finished. 109 | goto end 110 | ) 111 | 112 | if "%1" == "epub" ( 113 | %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub 114 | if errorlevel 1 exit /b 1 115 | echo. 116 | echo.Build finished. The epub file is in %BUILDDIR%/epub. 117 | goto end 118 | ) 119 | 120 | if "%1" == "latex" ( 121 | %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex 122 | if errorlevel 1 exit /b 1 123 | echo. 124 | echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. 125 | goto end 126 | ) 127 | 128 | if "%1" == "text" ( 129 | %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text 130 | if errorlevel 1 exit /b 1 131 | echo. 132 | echo.Build finished. The text files are in %BUILDDIR%/text. 133 | goto end 134 | ) 135 | 136 | if "%1" == "man" ( 137 | %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man 138 | if errorlevel 1 exit /b 1 139 | echo. 140 | echo.Build finished. The manual pages are in %BUILDDIR%/man. 141 | goto end 142 | ) 143 | 144 | if "%1" == "changes" ( 145 | %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes 146 | if errorlevel 1 exit /b 1 147 | echo. 148 | echo.The overview file is in %BUILDDIR%/changes. 149 | goto end 150 | ) 151 | 152 | if "%1" == "linkcheck" ( 153 | %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck 154 | if errorlevel 1 exit /b 1 155 | echo. 156 | echo.Link check complete; look for any errors in the above output ^ 157 | or in %BUILDDIR%/linkcheck/output.txt. 158 | goto end 159 | ) 160 | 161 | if "%1" == "doctest" ( 162 | %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest 163 | if errorlevel 1 exit /b 1 164 | echo. 165 | echo.Testing of doctests in the sources finished, look at the ^ 166 | results in %BUILDDIR%/doctest/output.txt. 167 | goto end 168 | ) 169 | 170 | :end 171 | -------------------------------------------------------------------------------- /readme.rst: -------------------------------------------------------------------------------- 1 | .. _index: 2 | 3 | Django 最佳实践 - 中文版 (2009-06-17) 4 | ========================================= 5 | 6 | :注意: 7 | 8 | 注意：英文指南 (`django-best-practices`_) 很久没有更新，这份译文的内容可能已经过时，仅用来参考，勿用来作为开发准则。 9 | 10 | :翻译: 11 | .. line-block:: 12 | 13 | `brantyoung `_ 14 | 15 | :项目主页: 16 | - `django-best-practices`_ 17 | - `django-best-practices - 中文版 `_ 18 | 19 | .. _readme: 20 | 21 | 译者 (yospaly) 前言 22 | -------------------- 23 | 24 | **Django 最佳实践** (`django-best-practices`_) 是 `django-reusable-app-docs`_ 的一个分支项目, 它在原有项目的理念上进行了扩展, 建立了一套关于 Django Web 开发方面的 "最佳实践" 规则, 这些理念超出了官方文档的讨论范围. 25 | 26 | 这份文档由一系列准则组成, 围绕这如何创建便于维护, 代码干净, 结构清晰, 方便复用, 易于部署的 Django 项目. 对于初学者, 它是一份不可多得指南, 如果不知道从何下手, 按照文档说做能很快规范起来; 对于经验丰富 Django 达人, 它也有一定的参考价值, 可以据此来创建自己的最佳实践准则. 27 | 28 | 原文是多页面方式, 不过 **实践** 每个规则的内容并不太多, 打散成多页面反而浏览不方便. 所以我把它们全合并到单个页面中, 除此之外, 没做其它改动. 29 | 30 | 原文和译文的源文件均使用 `reStructuredText `__ 格式, 可以用 `Sphinx `__ 转换成 HTML 等格式的文档. 31 | 32 | + `中文最新版本在线文档 `__ 33 | 34 | .. note:: 中文版力求保持和英文版同步更新. 当前版本 2009-06-17 11:32:35 35 | 36 | .. _best_practices: 37 | 38 | Django 最佳实践 39 | ================= 40 | 41 | 这是一份关于开发和部署 `Django Web 框架 `__ 的动态文档 (会随时更新). 这些准则不应该被认为是 *绝对正确* 或 *唯一* 使用 Django 的方法, 应该说这些最佳实践是我们使用框架多年来积累的经验. 42 | 43 | 本项目是 `django-reusable-app-docs 项目`_ 的一个分支, 这个优秀的项目是由 `Brian Rosner `__ 和 `Eric Holscher `_ 建立的, 是关于如何开发和维护可复用 Django apps 方面的最佳实践准则. 44 | 45 | .. _django-reusable-app-docs 项目: http://github.com/ericholscher/django-reusable-app-docs/ 46 | 47 | .. note:: 48 | 这份文档的源码放在 GitHub `django-best-practices`_ , 可以用 `Sphinx `__ 转换成多种文档格式 49 | 50 | .. _django-best-practices: http://github.com/lincolnloop/django-best-practices/ 51 | 52 | 53 | .. _code: 54 | .. index:: Coding Conventions, PEP 8, PEP 20 55 | pair: Python; Coding Conventions 56 | pair: Django; Coding Conventions 57 | 58 | 代码风格 59 | ---------- 60 | 61 | 一般而言, 代码应该干净, 简明, 易读. `The Zen of Python (PEP 20) `_ 是 Python 编码实践的权威介绍. 62 | 63 | + 尽可能合理的遵守 `Style Guide for Python Code (PEP 8) 64 | `__. 65 | + 遵守 `Django coding style 66 | `__. 68 | 69 | 70 | .. _apps: 71 | 72 | Django 应用 (app) 73 | ------------------- 74 | 75 | .. _apps-distribution: 76 | 77 | 如何发布我的 app ? 78 | ~~~~~~~~~~~~~~~~~~~~ 79 | 80 | Django 应该使用使用标准的 `Python Package Index 81 | `__ 即 Pypi 和 Cheese Shop. 我写过一篇关于如何 82 | 轻松打包和上传 app 到 Pypi 的 `教程 `__. 84 | 85 | 如果你上传 app 到 Pypi, 建议最好在你的项目名前加上 "django-" 前缀. 86 | 87 | (yospaly: 以下不解其意, 望达人指点) 88 | Also note, that when below when we refer to the default place for 89 | something as a file, that also means that you can make a directory of 90 | that same name; as per normal python. 91 | 92 | 93 | .. _apps-documentation: 94 | 95 | 文档 96 | ~~~~~~~~~~~~~~~~~~~~ 97 | 98 | + 放在和 APP 目录同级的 docs 目录中 (你的 app 应该有上级目录的吧?) 99 | + 可以包含模板, 供使用者参考 100 | 101 | 102 | .. _apps-overview: 103 | pair: What are; Reusable Apps 104 | triple: James Bennett; Djangocon Talk; Reusable Apps 105 | 106 | 什么是可复用 app? 107 | ~~~~~~~~~~~~~~~~~~~ 108 | 109 | 一个 Django app, 一个能够轻松嵌入到 project 的 app, 提供一个非常明确的功能. 110 | 它们应该专注并遵循 Unix 哲学 -- "做一件事并把它做好". 更多相关信息请参考 James Bennett 的 111 | `Djangocon talk `__. 112 | 113 | 114 | .. _apps-modules: 115 | 116 | Application 模块 117 | ~~~~~~~~~~~~~~~~~~~~~~ 118 | 119 | (yospaly: 以下所有大写单词, 如: APP, MODEL 等, 替换成你项目中真实的 app 名或 model 名.) 120 | 121 | .. _apps-admin: 122 | 123 | Admin 124 | ^^^^^^^^^^^^^ 125 | 126 | + 非必须 127 | + 放在 APP/admin.py 文件中 128 | + Admin 的 MODEL 类命名为 MODELAdmin 129 | 130 | .. _apps-context_processors: 131 | 132 | 上下文处理器 133 | ^^^^^^^^^^^^^^^^^^ 134 | 135 | + 放在 APP/context_processors.py 文件中 136 | 137 | 138 | 139 | .. _apps-feeds: 140 | 141 | 内容源 142 | ^^^^^^^^^^^^^^ 143 | 144 | + 放在 APP/feeds.py 文件中 145 | 146 | 147 | .. _apps-forms: 148 | 149 | 表单 150 | ^^^^^^^^^^^^^^ 151 | 152 | + 放在 APP/forms.py 文件中 153 | 154 | 155 | .. _apps-managers: 156 | 157 | Managers 158 | ^^^^^^^^^ 159 | 160 | + 放在 APP/managers.py 文件中 161 | 162 | 163 | .. _apps-middleware: 164 | 165 | 中间件 166 | ^^^^^^^^^^^^^^^^^^^^ 167 | 168 | + 放在 APP/middleware.py 文件中 169 | + 实现尽可能少的任务 170 | 171 | 172 | .. _apps-models: 173 | 174 | 模型 175 | ^^^^^^^^^^^^^^ 176 | 177 | + 放在 APP/models (.py 文件中或目录下) 178 | + 遵循 `Django's 模型约定 179 | `__ 181 | 182 | 183 | .. _apps-templates: 184 | 185 | 模板 186 | ^^^^^^^^^^^^^^^^^ 187 | 188 | + 放在 APP/templates/APP/template.html 文件中 189 | 190 | 为了尽量标准化 Django 模板区块 (block) 名称, 我建议通常情况下使用以下区块名称. 191 | 192 | + {% block title %} 193 | 194 | 这个区块用来定义页面的标题. 你的 base.html 模板很可能要在这个 tag 之外定义 195 | 站点名字 (Site's name) (即便使用了 Sites 框架), 以便能够放在所有页面中. 196 | 197 | 198 | + {% block extra_head %} 199 | 200 | 我认为这是个非常有用的区块, 很多人已经以某种方式在使用了. 201 | 很多页面经常需要在 HTML 文档头添加些信息, 比如 RSS 源, Javascript, 202 | CSS, 以及别的应该放在文档头的信息. 你可以, 也很可能将会, 定义另外专门的区块 203 | (比如前面的 title 区块) 来添加文档头的其它部分的信息. 204 | 205 | 206 | + {% block body %} 207 | 208 | 这个 tag 用来包含页面的整个 body 部分. 这使得你在 app 中创建的页面 209 | 能够替换整个页面内容, 不仅仅是正文内容. 这种做法虽不常见, 但当你需要时, 210 | 它确实是一个非常方便的 tag. 你可能还没注意到, 我一直尽可能的使 tag 211 | 名字和 HTML 标签名称保持一致. 212 | 213 | 214 | + {% block menu %} 215 | 216 | 你的菜单 (导航栏) 应该包含在这个区块中. 它是针对站点级的导航, 不是 217 | 每个页面专属的导航菜单. 218 | 219 | 220 | + {% block content %} 221 | 222 | 这个区块用来放置页面正文内容. 任何页面正文内容都可能不一样. 它不 223 | 包含任何站点导航, 信息头, 页脚, 或其它任何属于 base 模板的东东. 224 | 225 | 226 | 其它可能的区块 227 | ++++++++++++++++ 228 | 229 | 230 | + {% block content_title %} 231 | 232 | 用来指定 content 区块的 "title". 比如 blog 的标题. 也可以用来 233 | 包含 content 内的导航 (译注: 比如提纲), 或其它类似的东东. 大致都是些 234 | 页面中并非主要内容的东东. 我不知道这个区块是否应该放到 `content` tag 内, 235 | 并且对应于前面建议的 `content` tag, 是不是还需要一个 `main_content` 区块. 236 | 237 | + {% block header %} {% block footer %} 238 | 239 | 任何每个页面都可能修改的文本区域的页面和页脚. 240 | 241 | 242 | + {% block body_id %} {% block body_class %} 243 | 244 | 用来设置 HTML 文档 body 标签的 class 或 id 属性. 在设置样式或其它属性时 245 | 非常有用. 246 | 247 | 248 | + {% block [section]_menu %} {% block page_menu %} 249 | 250 | 这是对应于之前建议的 `menu` 区块. 用来导航一个章节或页面. 251 | 252 | 253 | .. _apps-templatetags: 254 | 255 | 模板标签 256 | ^^^^^^^^^^^^^^^^^^^^^^^^ 257 | 258 | 259 | + 放在 APP/templatetags/APP_tags.py 文件中 260 | 261 | 262 | 推荐的模板标签语法 263 | +++++++++++++++++++++++++ 264 | 265 | + as (Context Var): This is used to set a variable in the context of 266 | the page 267 | + for (object or app.model): This is used to designate an object for 268 | an action to be taken on. 269 | + limit (num): This is used to limit a result to a certain number of 270 | results. 271 | + exclude (object or pk): The same as for, but is used to exclude 272 | things of that type. 273 | 274 | 275 | .. _apps-tests: 276 | 277 | 测试 278 | ^^^^^^^^ 279 | 280 | + 放在 APP/tests (.py 文件或目录) 中 281 | + Fixtures 放在 APP/fixtures/fixture.json 文件中 282 | + 通常只须重写 Django 的 `testcase 283 | `__ 284 | 285 | 286 | .. _apps-urls: 287 | 288 | URLs 289 | ^^^^^^^^^^^^^^^^ 290 | 291 | + 放在 APP/urls (.py 文件或目录) 中 292 | + 需要设置 name 属性以便能够被反查; name 属性设置成 APP_MODEL_VIEW 的格式, 293 | 比如 blog_post_detail 或 blog_post_list. 294 | 295 | .. _apps-views: 296 | 297 | 视图 298 | ^^^^^^^^^^^^^^^^ 299 | 300 | + 放在 APP/views (.py 文件或目录) 中 301 | + 可以是任何可调用的 python 函数. 302 | + 视图参数应提供合理的缺省值, 并易于定制: 303 | 304 | 305 | 范例: 306 | 307 | .. sourcecode:: python 308 | 309 | def register(request, success_url=None, 310 | form_class=RegistrationForm 311 | template_name='registration/registration_form.html', 312 | extra_context=None): 313 | 314 | 315 | 316 | .. _projects: 317 | 318 | Django Projects (项目) 319 | ----------------------- 320 | 321 | .. _projects-layout: 322 | 323 | 推荐的布局 324 | ~~~~~~~~~~~~~~~~~~~~~~ 325 | 326 | .. sourcecode:: python 327 | 328 | example.com/ 329 | README 330 | settings.py 331 | urls.py 332 | docs/ 333 | This will hold the documentation for your project 334 | static/ 335 | -In production this will be the root of your MEDIA_URL 336 | css/ 337 | js/ 338 | images/ 339 | tests/ 340 | - Project level tests (Each app should also have tests) 341 | uploads/ 342 | - content imgs, etc 343 | templates/ 344 | - This area is used to override templates from your reusable apps 345 | flatpages/ 346 | comments/ 347 | example/ 348 | app1/ 349 | app2/ 350 | 351 | 352 | 353 | 354 | .. _projects-overview: 355 | 356 | 什么是 Django Project? 357 | ~~~~~~~~~~~~~~~~~~~~~~~~~ 358 | 359 | Django 中的 project 指的是一个包含设置文件, urls 链接, 以及一些 Django Apps 360 | 集合的简单结构. 这些东东可以是你自己写的, 也可以是一些包含在你的 project 内 361 | 的第三方代码. 362 | 363 | 364 | .. _projects-modules: 365 | 366 | Project 模块 367 | ~~~~~~~~~~~~~~~~~~~~~~ 368 | 369 | .. _projects-settings: 370 | 371 | 设置 372 | ^^^^^^^^^^^ 373 | 374 | 放在 ``[PROJECT]/settings.py`` 文件中 375 | 376 | 使用相对路径 377 | 378 | .. sourcecode:: python 379 | 380 | import os 381 | DIRNAME = os.path.dirname(__file__) 382 | 383 | MEDIA_ROOT = os.path.join(DIRNAME, 'static') 384 | 385 | 具体环境相关的设置使用 ``local_settings.py`` 文件, 并在 ``settings.py`` 文件结尾导入它. 386 | 387 | .. sourcecode:: python 388 | 389 | try: 390 | from local_settings import * 391 | except ImportError: 392 | pass 393 | 394 | 395 | .. _projects-urls: 396 | 397 | URLs 398 | ^^^^^^^^^^^ 399 | 400 | + 放在 PROJECT/urls.py 文件中 401 | + 应包含最少的逻辑代码, 多数情况下只作为一个指针, 指向你 apps 各自的 URL 配置. 402 | 403 | 404 | .. _deployment: 405 | 406 | 部署 407 | --------- 408 | 409 | .. _deployment-bootstrap: 410 | 411 | Project 的环境初始化 412 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 413 | 414 | .. index:: virtualenv, pip 415 | 416 | .. _deployment-filesystem_layout: 417 | 418 | 文件系统布局 419 | ^^^^^^^^^^^^^^^^^^^^^ 420 | 421 | .. note:: 本文档严重偏向 Unix 风格的文件系统, 要在其它操作系统上使用需要做些额外的修改. 422 | 423 | `Virtualenv `_ 对于 Python 项目来说是必须的. 它提供一个隔离不同 Python 运行环境的方法. 424 | 典型的, 我们在 ``/opt/webapps/`` 部署生产环境站点, 在 ``~/webapps/`` 目录部署我们的开发环境站点. 425 | 每个 project 有它自己的 ``virtualenv``, ``virtualenv`` 还充当 project 所有相关代码的根目录. 我们使用 ``pip`` 为 ``virtualenv`` 426 | 添加必要的包. 427 | 428 | 引导过程看上去是这样的: 429 | 430 | .. sourcecode:: bash 431 | 432 | cd /opt/webapps 433 | virtualenv mysite.com 434 | cd mysite.com 435 | pip install -E . -r path/to/requirements.txt 436 | source bin/activate 437 | 438 | .. tip:: 方便起见, 你可以在你的 ``virtualenv`` 根目录中创建 Django project 的符号链接. 符号链接的名字无所谓, 因为你的 project 已经在 Python 搜索路径中. 通过给你所有的 projects 起同样的符号链接名, 你可以使用一些 `方便的 bash 函数以节省时间 `_. 439 | 440 | .. index:: pip, requirements.txt 441 | 442 | 443 | .. _deployment-packaging: 444 | 445 | 打包 446 | ^^^^^^^^^^^^^^^^^^^^^ 447 | 448 | 成功部署的关键之一是, 保证你开发环境下的软件尽可能接近部署环境下的软件. `Pip `_ 提供了一个简单的重现方法, 让你在任何系统上都能非常一致的部署 Python 项目. 任何需要第三方库的 app 都应该包含一个名为 ``requirements.txt`` 的 `pip 规格文件 `_. Projects 应到负责汇集所有 app 的规格文件, 并在根据需要添加其它规格. 449 | 450 | .. rubric:: 你的规格文件中要包含些什么 451 | 452 | 我们的经验是, 任何应用程序, 只要你的操作系统默认没附带. 唯一需要从我们的规格文件中剔除的几个包是 ``PIL``, 数据库驱动和其它 ``pip`` 不能安装的包. 这些被剔除的规格放在 :ref:`project's README ` 文件中加以说明. 453 | 454 | 455 | .. _deployment-servers: 456 | 457 | 服务器 458 | ~~~~~~~~~~~~~~~~~~~~~~~ 459 | 460 | .. note:: 部署架构很大程度上取决于站点的流量. 下面描述的设置对我们来说, 在大多数情况下工作的最好. 461 | 462 | 我们基于 Linux 和 PostgreSQL 后端数据库部署 Django, `Nginx `__ 进程作为前端代理, 处在其后的是 Apache 和 `mod_wsgi `__. 463 | 464 | .. _deployment-nginx: 465 | 466 | .. index:: Nginx 467 | 468 | Nginx 469 | ^^^^^^^^^^^ 470 | 471 | `Nginx `__ 是一个非常优秀的前端服务器, 速度快, 稳如磐石, 并且资源占用很少. 以下是一个典型的 Nginx 站点配置: 472 | 473 | .. literalinclude:: /examples/nginx.conf 474 | :language: nginx 475 | 476 | .. rubric:: 它都做些什么? 477 | 478 | 第一段告诉 Nginx 去哪里找托管了 Django 站点的服务器. 第二段把所有来自 ``www.domain.com`` 的请求重定向到 ``domain.com``, 这样所有资源就都只有一个 URL 能被访问到. 最后一段承担了所有工作. 它告诉 Nginx 检查 ``/var/www/domain.com`` 中是否存在被请求的文件. 如果存在, 它返回该文件, 否则, 它将把请求转发给 Django 站点. 479 | 480 | .. warning:: yospaly 注 481 | 482 | 以下涉及 Apache 的部分均未作翻译, 我们强烈建议使用 Nginx/Lighttpd + SCGI/FastCGI/HTTP 的方式, 尽量不要使用繁琐的 Apache + mod_wsgi. 483 | 484 | .. index:: 485 | pair: Nginx; SSL 486 | 487 | SSL 488 | ^^^ 489 | 490 | Another benefit to running a frontend server is lightweight SSL proxying. Rather than having two Django instances running for SSL and non-SSL access, we can have Nginx act as the gatekeeper redirecting all requests back to a single non-SSL Apache instance listening on the ``localhost``. Here's what that would look like: 491 | 492 | .. literalinclude:: /examples/nginx_ssl.conf 493 | :language: nginx 494 | 495 | You can include this code at the bottom of your non-SSL configuration file. 496 | 497 | .. tip:: For SSL-aware Django sites like `Satchmo `_, you'll need to "trick" the site into thinking incoming requests are coming in via SSL, but this is simple enough to do with `a small addition to the WSGI script `_ we discuss below. 498 | 499 | .. index:: Apache 500 | pair: Apache; mod_wsgi 501 | pair: Apache; Worker MPM 502 | pair: Apache; Listen 503 | 504 | Apache 505 | ------ 506 | 507 | We run the Apache2 Worker MPM with `mod_wsgi `__ in daemon mode. The default settings for the MPM Worker module should be sufficient for most environments although those with a shortage of RAM may want to look into reducing the number of servers spawned. Since Nginx will be listening for HTTP(S) requests, you'll need to bind Apache to a different port. While you're at it, you can tell it to only respond to the ``localhost``. To do so, you'll want to edit the `Listen directive `_ 508 | 509 | .. sourcecode:: apache 510 | 511 | Listen 127.0.0.1:9000 512 | 513 | .. index:: mod_wsgi 514 | 515 | With Apache up and running, you'll need an Apache configuration and WSGI script for each site. A typical Apache configuration for an individual site looks like this: 516 | 517 | .. literalinclude:: /examples/apache.conf 518 | :language: apache 519 | 520 | .. index:: 521 | pair: mod_wsgi; maximum-requests 522 | 523 | .. tip:: In a perfect world, your app would never leak memory and you can leave out the ``maximum-requests`` directive. In our experience, setting this to a high number is nice to keep Apache's memory usage in check. 524 | 525 | .. warning:: This will default to a single process with 15 threads. Django is not "officially" thread safe and some external libraries (notably a couple required for ``django.contrib.gis``) are known to not be thread safe. If needed the ``threads`` and ``processes`` arguments can be adjusted accordingly. 526 | 527 | It links to the WSGI script within the project directory. The script is just a few lines of Python to properly setup our environment. 528 | 529 | .. literalinclude:: /examples/django.wsgi 530 | :language: python 531 | --------------------------------------------------------------------------------