Merge lp:~canonical-isd-hackers/django-preflight/documentation into lp:django-preflight
- documentation
- Merge into trunk
Proposed by
Łukasz Czyżykowski
Status: | Merged |
---|---|
Merged at revision: | 5 |
Proposed branch: | lp:~canonical-isd-hackers/django-preflight/documentation |
Merge into: | lp:django-preflight |
Diff against target: |
797 lines (+717/-2) 12 files modified
.bzrignore (+2/-1) README (+25/-0) doc/Makefile (+89/-0) doc/authentication.rst (+61/-0) doc/conf.py (+196/-0) doc/configure.rst (+28/-0) doc/creating-checks.rst (+85/-0) doc/index.rst (+25/-0) doc/install.rst (+75/-0) doc/manage-command.rst (+42/-0) doc/versions.rst (+79/-0) tox.ini (+10/-1) |
To merge this branch: | bzr merge lp:~canonical-isd-hackers/django-preflight/documentation |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Anthony Lenton (community) | Approve | ||
Review via email: mp+49191@code.launchpad.net |
Commit message
Add documentation.
Description of the change
Add documentation for project.
To post a comment you must log in.
- 10. By Łukasz Czyżykowski
-
Removed doc/_build from the branch.
- 11. By Łukasz Czyżykowski
-
Fixed typos in docs.
Preview Diff
[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1 | === modified file '.bzrignore' |
2 | --- .bzrignore 2011-02-07 16:06:51 +0000 |
3 | +++ .bzrignore 2011-02-10 12:30:10 +0000 |
4 | @@ -2,4 +2,5 @@ |
5 | build |
6 | dist |
7 | .tox |
8 | -*.egg-info |
9 | \ No newline at end of file |
10 | +*.egg-info |
11 | +doc/_build |
12 | \ No newline at end of file |
13 | |
14 | === removed file 'INSTALL' |
15 | === modified file 'README' |
16 | --- README 2011-02-07 16:06:51 +0000 |
17 | +++ README 2011-02-10 12:30:10 +0000 |
18 | @@ -0,0 +1,25 @@ |
19 | +================= |
20 | +Django Pre-flight |
21 | +================= |
22 | + |
23 | +Overview |
24 | +======== |
25 | + |
26 | +Django Pre-flight is meant to help with creation of simple pages on |
27 | +which one can quickly gauge health of the system and its external |
28 | +dependencies. It's a great help for testers before actually delving |
29 | +into the system to be sure that all is configured correctly and any |
30 | +found problems are due to bugs in the code itself and not because of |
31 | +misconfiguration. |
32 | + |
33 | +This project provides framework for creating set of checks (methods) |
34 | +which determine the health of the system, a way of executing all of |
35 | +them and gathering the results. You can either see the result via the |
36 | +web interface or using Django's ``manage.py`` command. |
37 | + |
38 | +Additionally the web page displays the versions of various system |
39 | +components, like Python, Django, django-preflight itself. This |
40 | +versions list also have a way of extending it to include project's |
41 | +specific bits of information. |
42 | + |
43 | +More information can be found in ``doc/`` directory. |
44 | |
45 | === added directory 'doc' |
46 | === added file 'doc/Makefile' |
47 | --- doc/Makefile 1970-01-01 00:00:00 +0000 |
48 | +++ doc/Makefile 2011-02-10 12:30:10 +0000 |
49 | @@ -0,0 +1,89 @@ |
50 | +# Makefile for Sphinx documentation |
51 | +# |
52 | + |
53 | +# You can set these variables from the command line. |
54 | +SPHINXOPTS = |
55 | +SPHINXBUILD = sphinx-build |
56 | +PAPER = |
57 | +BUILDDIR = _build |
58 | + |
59 | +# Internal variables. |
60 | +PAPEROPT_a4 = -D latex_paper_size=a4 |
61 | +PAPEROPT_letter = -D latex_paper_size=letter |
62 | +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . |
63 | + |
64 | +.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest |
65 | + |
66 | +help: |
67 | + @echo "Please use \`make <target>' where <target> is one of" |
68 | + @echo " html to make standalone HTML files" |
69 | + @echo " dirhtml to make HTML files named index.html in directories" |
70 | + @echo " pickle to make pickle files" |
71 | + @echo " json to make JSON files" |
72 | + @echo " htmlhelp to make HTML files and a HTML help project" |
73 | + @echo " qthelp to make HTML files and a qthelp project" |
74 | + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" |
75 | + @echo " changes to make an overview of all changed/added/deprecated items" |
76 | + @echo " linkcheck to check all external links for integrity" |
77 | + @echo " doctest to run all doctests embedded in the documentation (if enabled)" |
78 | + |
79 | +clean: |
80 | + -rm -rf $(BUILDDIR)/* |
81 | + |
82 | +html: |
83 | + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html |
84 | + @echo |
85 | + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." |
86 | + |
87 | +dirhtml: |
88 | + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml |
89 | + @echo |
90 | + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." |
91 | + |
92 | +pickle: |
93 | + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle |
94 | + @echo |
95 | + @echo "Build finished; now you can process the pickle files." |
96 | + |
97 | +json: |
98 | + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json |
99 | + @echo |
100 | + @echo "Build finished; now you can process the JSON files." |
101 | + |
102 | +htmlhelp: |
103 | + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp |
104 | + @echo |
105 | + @echo "Build finished; now you can run HTML Help Workshop with the" \ |
106 | + ".hhp project file in $(BUILDDIR)/htmlhelp." |
107 | + |
108 | +qthelp: |
109 | + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp |
110 | + @echo |
111 | + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ |
112 | + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" |
113 | + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/django-preflight.qhcp" |
114 | + @echo "To view the help file:" |
115 | + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/django-preflight.qhc" |
116 | + |
117 | +latex: |
118 | + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex |
119 | + @echo |
120 | + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." |
121 | + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ |
122 | + "run these through (pdf)latex." |
123 | + |
124 | +changes: |
125 | + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes |
126 | + @echo |
127 | + @echo "The overview file is in $(BUILDDIR)/changes." |
128 | + |
129 | +linkcheck: |
130 | + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck |
131 | + @echo |
132 | + @echo "Link check complete; look for any errors in the above output " \ |
133 | + "or in $(BUILDDIR)/linkcheck/output.txt." |
134 | + |
135 | +doctest: |
136 | + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest |
137 | + @echo "Testing of doctests in the sources finished, look at the " \ |
138 | + "results in $(BUILDDIR)/doctest/output.txt." |
139 | |
140 | === added directory 'doc/_static' |
141 | === added directory 'doc/_templates' |
142 | === added file 'doc/authentication.rst' |
143 | --- doc/authentication.rst 1970-01-01 00:00:00 +0000 |
144 | +++ doc/authentication.rst 2011-02-10 12:30:10 +0000 |
145 | @@ -0,0 +1,61 @@ |
146 | +Authentication |
147 | +============== |
148 | + |
149 | + |
150 | +Defaults |
151 | +-------- |
152 | + |
153 | +Due to high sensitivity of the information provided on preflight page |
154 | +it's highly advisable to limit access to it. |
155 | + |
156 | +By default only registered users which have access to Django admin can |
157 | +see that page and all the rest will get a 404 error page. |
158 | + |
159 | + |
160 | +Customization |
161 | +------------- |
162 | + |
163 | +But if this is not enough or if you need some other way of assesing |
164 | +the access right you can provide your own code. |
165 | + |
166 | +Each preflight class can have an ``authenticate(self, request)`` |
167 | +method which gets a request object and returns ``True`` if given |
168 | +request is authorized to access that page. Otherwise the 404 error |
169 | +code will be returned. |
170 | + |
171 | + |
172 | +Multiple preflight files |
173 | +------------------------ |
174 | + |
175 | +As you may have noticed, the ``authenticate`` method is supplied for |
176 | +each application and not for whole project. This brings the question |
177 | +what would happen if two or more applications contain ``authenticate`` |
178 | +method? |
179 | + |
180 | +In that case, given request must have be approved by all the |
181 | +``authentication`` methods before the page is displayed. It's enough |
182 | +for just one to veto the access. This means, that you can only tighten |
183 | +up the security when adding new preflight classes, never loosen it up. |
184 | + |
185 | + |
186 | +Example |
187 | +------- |
188 | + |
189 | +Below is quick example of implementing very simple way of |
190 | +authorization schema. This particular one only allows one user to |
191 | +access this page: |
192 | + |
193 | +.. testcode:: |
194 | + |
195 | + import preflight |
196 | + |
197 | + class AppPreflight(preflight.Preflight): |
198 | + |
199 | + def authenticate(self, request): |
200 | + if request.user.username == 'blackknight': |
201 | + return True |
202 | + |
203 | + preflight.register(AppPreflight) |
204 | + |
205 | +.. testoutput:: |
206 | + :hide: |
207 | |
208 | === added file 'doc/conf.py' |
209 | --- doc/conf.py 1970-01-01 00:00:00 +0000 |
210 | +++ doc/conf.py 2011-02-10 12:30:10 +0000 |
211 | @@ -0,0 +1,196 @@ |
212 | +# -*- coding: utf-8 -*- |
213 | +# |
214 | +# django-preflight documentation build configuration file, created by |
215 | +# sphinx-quickstart on Tue Feb 8 15:23:58 2011. |
216 | +# |
217 | +# This file is execfile()d with the current directory set to its containing dir. |
218 | +# |
219 | +# Note that not all possible configuration values are present in this |
220 | +# autogenerated file. |
221 | +# |
222 | +# All configuration values have a default; values that are commented out |
223 | +# serve to show the default. |
224 | + |
225 | +import sys, os |
226 | + |
227 | +# If extensions (or modules to document with autodoc) are in another directory, |
228 | +# add these directories to sys.path here. If the directory is relative to the |
229 | +# documentation root, use os.path.abspath to make it absolute, like shown here. |
230 | +sys.path.append(os.path.abspath('..')) |
231 | + |
232 | +os.environ['DJANGO_SETTINGS_MODULE'] = 'example_project.settings' |
233 | + |
234 | +# -- General configuration ----------------------------------------------------- |
235 | + |
236 | +# Add any Sphinx extension module names here, as strings. They can be extensions |
237 | +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. |
238 | +extensions = ['sphinx.ext.doctest'] |
239 | + |
240 | +# Add any paths that contain templates here, relative to this directory. |
241 | +templates_path = ['_templates'] |
242 | + |
243 | +# The suffix of source filenames. |
244 | +source_suffix = '.rst' |
245 | + |
246 | +# The encoding of source files. |
247 | +#source_encoding = 'utf-8' |
248 | + |
249 | +# The master toctree document. |
250 | +master_doc = 'index' |
251 | + |
252 | +# General information about the project. |
253 | +project = u'django-preflight' |
254 | +copyright = u'2011, Łukasz Czyżykowski' |
255 | + |
256 | +# The version info for the project you're documenting, acts as replacement for |
257 | +# |version| and |release|, also used in various other places throughout the |
258 | +# built documents. |
259 | +# |
260 | +# The short X.Y version. |
261 | +version = '0.1' |
262 | +# The full version, including alpha/beta/rc tags. |
263 | +release = '0.1' |
264 | + |
265 | +# The language for content autogenerated by Sphinx. Refer to documentation |
266 | +# for a list of supported languages. |
267 | +#language = None |
268 | + |
269 | +# There are two options for replacing |today|: either, you set today to some |
270 | +# non-false value, then it is used: |
271 | +#today = '' |
272 | +# Else, today_fmt is used as the format for a strftime call. |
273 | +#today_fmt = '%B %d, %Y' |
274 | + |
275 | +# List of documents that shouldn't be included in the build. |
276 | +#unused_docs = [] |
277 | + |
278 | +# List of directories, relative to source directory, that shouldn't be searched |
279 | +# for source files. |
280 | +exclude_trees = ['_build'] |
281 | + |
282 | +# The reST default role (used for this markup: `text`) to use for all documents. |
283 | +#default_role = None |
284 | + |
285 | +# If true, '()' will be appended to :func: etc. cross-reference text. |
286 | +#add_function_parentheses = True |
287 | + |
288 | +# If true, the current module name will be prepended to all description |
289 | +# unit titles (such as .. function::). |
290 | +#add_module_names = True |
291 | + |
292 | +# If true, sectionauthor and moduleauthor directives will be shown in the |
293 | +# output. They are ignored by default. |
294 | +#show_authors = False |
295 | + |
296 | +# The name of the Pygments (syntax highlighting) style to use. |
297 | +pygments_style = 'sphinx' |
298 | + |
299 | +# A list of ignored prefixes for module index sorting. |
300 | +#modindex_common_prefix = [] |
301 | + |
302 | + |
303 | +# -- Options for HTML output --------------------------------------------------- |
304 | + |
305 | +# The theme to use for HTML and HTML Help pages. Major themes that come with |
306 | +# Sphinx are currently 'default' and 'sphinxdoc'. |
307 | +html_theme = 'default' |
308 | + |
309 | +# Theme options are theme-specific and customize the look and feel of a theme |
310 | +# further. For a list of options available for each theme, see the |
311 | +# documentation. |
312 | +#html_theme_options = {} |
313 | + |
314 | +# Add any paths that contain custom themes here, relative to this directory. |
315 | +#html_theme_path = [] |
316 | + |
317 | +# The name for this set of Sphinx documents. If None, it defaults to |
318 | +# "<project> v<release> documentation". |
319 | +#html_title = None |
320 | + |
321 | +# A shorter title for the navigation bar. Default is the same as html_title. |
322 | +#html_short_title = None |
323 | + |
324 | +# The name of an image file (relative to this directory) to place at the top |
325 | +# of the sidebar. |
326 | +#html_logo = None |
327 | + |
328 | +# The name of an image file (within the static path) to use as favicon of the |
329 | +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 |
330 | +# pixels large. |
331 | +#html_favicon = None |
332 | + |
333 | +# Add any paths that contain custom static files (such as style sheets) here, |
334 | +# relative to this directory. They are copied after the builtin static files, |
335 | +# so a file named "default.css" will overwrite the builtin "default.css". |
336 | +html_static_path = ['_static'] |
337 | + |
338 | +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, |
339 | +# using the given strftime format. |
340 | +#html_last_updated_fmt = '%b %d, %Y' |
341 | + |
342 | +# If true, SmartyPants will be used to convert quotes and dashes to |
343 | +# typographically correct entities. |
344 | +#html_use_smartypants = True |
345 | + |
346 | +# Custom sidebar templates, maps document names to template names. |
347 | +#html_sidebars = {} |
348 | + |
349 | +# Additional templates that should be rendered to pages, maps page names to |
350 | +# template names. |
351 | +#html_additional_pages = {} |
352 | + |
353 | +# If false, no module index is generated. |
354 | +#html_use_modindex = True |
355 | + |
356 | +# If false, no index is generated. |
357 | +#html_use_index = True |
358 | + |
359 | +# If true, the index is split into individual pages for each letter. |
360 | +#html_split_index = False |
361 | + |
362 | +# If true, links to the reST sources are added to the pages. |
363 | +#html_show_sourcelink = True |
364 | + |
365 | +# If true, an OpenSearch description file will be output, and all pages will |
366 | +# contain a <link> tag referring to it. The value of this option must be the |
367 | +# base URL from which the finished HTML is served. |
368 | +#html_use_opensearch = '' |
369 | + |
370 | +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). |
371 | +#html_file_suffix = '' |
372 | + |
373 | +# Output file base name for HTML help builder. |
374 | +htmlhelp_basename = 'django-preflightdoc' |
375 | + |
376 | + |
377 | +# -- Options for LaTeX output -------------------------------------------------- |
378 | + |
379 | +# The paper size ('letter' or 'a4'). |
380 | +#latex_paper_size = 'letter' |
381 | + |
382 | +# The font size ('10pt', '11pt' or '12pt'). |
383 | +#latex_font_size = '10pt' |
384 | + |
385 | +# Grouping the document tree into LaTeX files. List of tuples |
386 | +# (source start file, target name, title, author, documentclass [howto/manual]). |
387 | +latex_documents = [ |
388 | + ('index', 'django-preflight.tex', u'django-preflight Documentation', |
389 | + u'Łukasz Czyżykowski', 'manual'), |
390 | +] |
391 | + |
392 | +# The name of an image file (relative to this directory) to place at the top of |
393 | +# the title page. |
394 | +#latex_logo = None |
395 | + |
396 | +# For "manual" documents, if this is true, then toplevel headings are parts, |
397 | +# not chapters. |
398 | +#latex_use_parts = False |
399 | + |
400 | +# Additional stuff for the LaTeX preamble. |
401 | +#latex_preamble = '' |
402 | + |
403 | +# Documents to append as an appendix to all manuals. |
404 | +#latex_appendices = [] |
405 | + |
406 | +# If false, no module index is generated. |
407 | +#latex_use_modindex = True |
408 | |
409 | === added file 'doc/configure.rst' |
410 | --- doc/configure.rst 1970-01-01 00:00:00 +0000 |
411 | +++ doc/configure.rst 2011-02-10 12:30:10 +0000 |
412 | @@ -0,0 +1,28 @@ |
413 | +Configuration |
414 | +============= |
415 | + |
416 | +You can customize django-preflight's behaviour in several |
417 | +ways. Easiest one is to use configuration options. |
418 | + |
419 | + |
420 | +``settings.py`` |
421 | +--------------- |
422 | + |
423 | +``PREFLIGHT_BASE_TEMPLATE`` Name of the base template which will be |
424 | + extended by preflight's page. It should contain ``title`` and |
425 | + ``content`` blocks. |
426 | + |
427 | + Default: ``index.1col.html`` |
428 | + |
429 | +``PREFLIGHT_TABLE_CLASS`` |
430 | + A name of the CSS class which will be applied to the tables on the |
431 | + overview page. |
432 | + |
433 | + Default: ``listing`` |
434 | + |
435 | + |
436 | +Other customizations |
437 | +-------------------- |
438 | + |
439 | +Other ways in which you can customize django-preflight are tightly |
440 | +coupled with creating checks and are discussed in the next section. |
441 | |
442 | === added file 'doc/creating-checks.rst' |
443 | --- doc/creating-checks.rst 1970-01-01 00:00:00 +0000 |
444 | +++ doc/creating-checks.rst 2011-02-10 12:30:10 +0000 |
445 | @@ -0,0 +1,85 @@ |
446 | +Creating checks |
447 | +=============== |
448 | + |
449 | +Conventions |
450 | +----------- |
451 | + |
452 | +There are four steps to create a check: |
453 | + |
454 | + 1. Create ``preflight.py`` file in your application's directory. |
455 | + 2. In that file create a class which inherits from |
456 | + ``preflight.Preflight``. |
457 | + 3. Add a method to that class with name starting with ``check_``. |
458 | + 4. Register that class by calling ``preflight.register(ClassName)`` |
459 | + |
460 | +Those check methods are used by web interface and by command line |
461 | +one. You can see the results of them being run by either accessing the |
462 | +preflight page or by running ``$ ./manage.py preflight`` command. |
463 | + |
464 | + |
465 | +Check's description |
466 | +------------------- |
467 | + |
468 | +The docstring of the method is displayed on the web page as a |
469 | +description of the check. You can use it to document what it is |
470 | +checking and what to do in case it fails. Ideally, one should check |
471 | +only one thing, so reason of the failure would be obvious. |
472 | + |
473 | + |
474 | +Success or Failure |
475 | +------------------ |
476 | + |
477 | +To the check to be considered successful it needs to return a |
478 | +``True``. Returning ``False`` or raising an exception means that the |
479 | +check have failed. The system records the results from all the checks |
480 | +from all of the applications and presents it to the end user. |
481 | + |
482 | + |
483 | +An Example |
484 | +---------- |
485 | + |
486 | +Below is an example of simple preflight class which checks if cache is |
487 | +accessible from Django's process: |
488 | + |
489 | +.. testcode:: |
490 | + |
491 | + # this line is required for Python versions < |
492 | + from __future__ import absolute_import |
493 | + |
494 | + import preflight |
495 | + |
496 | + |
497 | + class AppPreflight(preflight.Preflight): |
498 | + |
499 | + def check_cache_is_accessible(self): |
500 | + """ |
501 | + Try to access cache, if it fails that means the caching |
502 | + is not properly configured or the cache server is down. |
503 | + """ |
504 | + from django.core.cache import cache |
505 | + cache.set('test', 'value') |
506 | + if cache.get('test') == 'value': |
507 | + cache.delete('test') |
508 | + return True |
509 | + else: |
510 | + return False |
511 | + |
512 | + preflight.register(AppPreflight) |
513 | + |
514 | +.. testoutput:: |
515 | + :hide: |
516 | + |
517 | +If everything is properly configured this check method will return |
518 | +``True``, which means that it succeeded. |
519 | + |
520 | +But if something is wrong, like, for example, missing python-memcached |
521 | +library, the exception will be raised and will cause this check to |
522 | +fail. |
523 | + |
524 | +Third option is when this check returns ``False``, which means |
525 | +that the cache is accessible, but is not storing proper values. Not a |
526 | +good sign either. |
527 | + |
528 | +.. note:: I'm aware this check can fail for more than one reason. It |
529 | + would be possible to split it into two smaller checks, but |
530 | + that would only made this example more complicated. |
531 | |
532 | === added file 'doc/index.rst' |
533 | --- doc/index.rst 1970-01-01 00:00:00 +0000 |
534 | +++ doc/index.rst 2011-02-10 12:30:10 +0000 |
535 | @@ -0,0 +1,25 @@ |
536 | +.. django-preflight documentation master file, created by |
537 | + sphinx-quickstart on Tue Feb 8 15:23:58 2011. |
538 | + You can adapt this file completely to your liking, but it should at least |
539 | + contain the root `toctree` directive. |
540 | + |
541 | +Welcome to django-preflight's documentation! |
542 | +============================================ |
543 | + |
544 | +Contents: |
545 | + |
546 | +.. toctree:: |
547 | + :maxdepth: 2 |
548 | + |
549 | + install |
550 | + configure |
551 | + creating-checks |
552 | + authentication |
553 | + versions |
554 | + manage-command |
555 | + |
556 | +Search |
557 | +====== |
558 | + |
559 | +* :ref:`search` |
560 | + |
561 | |
562 | === added file 'doc/install.rst' |
563 | --- doc/install.rst 1970-01-01 00:00:00 +0000 |
564 | +++ doc/install.rst 2011-02-10 12:30:10 +0000 |
565 | @@ -0,0 +1,75 @@ |
566 | +Install django-preflight |
567 | +======================== |
568 | + |
569 | +Install the code |
570 | +---------------- |
571 | + |
572 | +django-preflight is just a regular Django application and only |
573 | +requirement for it to be usable is to be importable by Django |
574 | +project. That means you can put it directly into your project's |
575 | +directory and it will work just find. Alternatively you can install it |
576 | +using common python tools::: |
577 | + |
578 | + $ pip install django-preflight |
579 | + |
580 | +or:: |
581 | + |
582 | + $ easy_install django-preflight |
583 | + |
584 | +Or even download the source code and run:: |
585 | + |
586 | + $ python setup.py install |
587 | + |
588 | +from the source code directory. |
589 | + |
590 | + |
591 | +Update ``settings.py`` |
592 | +---------------------- |
593 | + |
594 | +Once the code is installed you need to setup your Django's project |
595 | +properly. First thing is to include it in ``INSTALLED_APPS`` list:: |
596 | + |
597 | + # settings.py |
598 | + INSTALLED_APPS = ( |
599 | + ... |
600 | + 'preflight', |
601 | + ... |
602 | + ) |
603 | + |
604 | +django-preflight by itself doesn't have any extra dependecies. |
605 | + |
606 | +Because this project doesn't include any database models, there's no |
607 | +need of updating your database schema. |
608 | + |
609 | + |
610 | +Update ``urls.py`` |
611 | +------------------ |
612 | + |
613 | +Last bit of configuration is to include django-preflight into the |
614 | +project's ``urls.py`` file. It should look like the following: |
615 | + |
616 | +.. testcode:: |
617 | + |
618 | + from django.conf.urls.defaults import * |
619 | + |
620 | + import preflight |
621 | + import preflight.urls |
622 | + |
623 | + |
624 | + preflight.autodiscover() |
625 | + |
626 | + urlpatterns = patterns('', |
627 | + (r'^preflight/', include(preflight.urls)), |
628 | + ) |
629 | + |
630 | +.. testoutput:: |
631 | + :hide: |
632 | + |
633 | +Two things here. Line with ``include(preflight.urls)`` sets the URL on |
634 | +which the preflight page will be accessible. You can make this |
635 | +anything you want, here it's set to ``/preflight/``. |
636 | + |
637 | +Second is ``preflight.autodiscover()`` call which triggers search for |
638 | +``preflight.py`` modules in all installed applications. Similar to |
639 | +Django's admin ``admin.autodiscover()`` call. This enables you to |
640 | +just drop such file into your application folder. |
641 | |
642 | === added file 'doc/manage-command.rst' |
643 | --- doc/manage-command.rst 1970-01-01 00:00:00 +0000 |
644 | +++ doc/manage-command.rst 2011-02-10 12:30:10 +0000 |
645 | @@ -0,0 +1,42 @@ |
646 | +Management Command |
647 | +================== |
648 | + |
649 | + |
650 | +Command |
651 | +------- |
652 | + |
653 | +Together with web page on which you can check the results of all your |
654 | +checks django-preflight provides a Django management command. This |
655 | +allows you to make sure that all is properly configured without the |
656 | +need of going through the web server. |
657 | + |
658 | +It can even be incorporated as a part of automatic health checks (or |
659 | +other scripts), as it properly returns the exit codes. 0 if everything |
660 | +is working and 1 otherwise. |
661 | + |
662 | + |
663 | +Usage |
664 | +----- |
665 | + |
666 | +The invocation of the command is very simple. Once you have the app |
667 | +installed just use:: |
668 | + |
669 | + $ python manage.py preflight |
670 | + |
671 | +which should return something similar to the following:: |
672 | + |
673 | + Pre-flight checks for applications |
674 | + ==================================================== |
675 | + |
676 | + app checks |
677 | + ---------------------------------------------------- |
678 | + media_root_is_writable OK |
679 | + cache_is_usable OK |
680 | + twitter_api_key_is_correct OK |
681 | + |
682 | + |
683 | +of course, the exact result will highly depend on the exact checks, |
684 | +project's structure and django-preflight configuration. |
685 | + |
686 | +In case of any check failures the ``OK`` will be replaced with |
687 | +``ERROR`` status. |
688 | |
689 | === added file 'doc/versions.rst' |
690 | --- doc/versions.rst 1970-01-01 00:00:00 +0000 |
691 | +++ doc/versions.rst 2011-02-10 12:30:10 +0000 |
692 | @@ -0,0 +1,79 @@ |
693 | +Versions |
694 | +======== |
695 | + |
696 | +Version's List |
697 | +-------------- |
698 | + |
699 | +Besides checks django-preflight provides a list of versions for |
700 | +various components. That information is only accessible via web |
701 | +interface, because it's very easy to get that information from the |
702 | +command line. |
703 | + |
704 | +Naturally you have an ability to extend this information with any |
705 | +other component you like. By default it contains versions of: Python, |
706 | +Django and django-preflight itself. |
707 | + |
708 | + |
709 | +Extending Versions List |
710 | +----------------------- |
711 | + |
712 | +As with other things, main extension point is ``Preflight`` class. You |
713 | +can either add ``versions(self)`` method, which should return list of |
714 | +dictionaries, each one containing ``name`` and ``version`` keys or add |
715 | +class attribute called ``versions`` containing the same information. |
716 | + |
717 | +The method version can be useful if you want to check some items |
718 | +dynamically or include them only if they are available and skipping |
719 | +them otherwise. |
720 | + |
721 | + |
722 | +Method Example |
723 | +-------------- |
724 | + |
725 | +An example where ``versions`` is a method: |
726 | + |
727 | +.. testcode:: |
728 | + |
729 | + import preflight |
730 | + |
731 | + class AppPreflight(preflight.Preflight): |
732 | + def versions(self): |
733 | + try: |
734 | + import simplejson |
735 | + return [{'name': "simplejson", |
736 | + 'version': simplejson.__version__}] |
737 | + except ImportError: |
738 | + return [] |
739 | + |
740 | + preflight.register(AppPreflight) |
741 | + |
742 | +.. testoutput:: |
743 | + :hide: |
744 | + |
745 | +In this case, if simplejson is available its version will be added to |
746 | +the list of packages displayed by django-preflight. |
747 | + |
748 | + |
749 | +Attribute Example |
750 | +----------------- |
751 | + |
752 | +An example where ``versions`` is an iterable: |
753 | + |
754 | +.. testcode:: |
755 | + |
756 | + import preflight |
757 | + import setuptools |
758 | + |
759 | + class AppPreflight(preflight.Preflight): |
760 | + |
761 | + versions = [ |
762 | + {'name': "setuptools", 'version': setuptools.__version__} |
763 | + ] |
764 | + |
765 | + preflight.register(AppPreflight) |
766 | + |
767 | +.. testoutput:: |
768 | + :hide: |
769 | + |
770 | +On the other hand, this example causes the app to require |
771 | +``setuptools`` to be installed and will fail if this is not the case. |
772 | |
773 | === modified file 'tox.ini' |
774 | --- tox.ini 2011-02-07 16:06:51 +0000 |
775 | +++ tox.ini 2011-02-10 12:30:10 +0000 |
776 | @@ -1,11 +1,20 @@ |
777 | [tox] |
778 | envlist = |
779 | py26-django124, py26-django113, py26-django104, py26-django-beta, |
780 | - py27-django124, py27-django113, py27-django104, py27-django-beta |
781 | + py27-django124, py27-django113, py27-django104, py27-django-beta, |
782 | + docs |
783 | |
784 | [testenv] |
785 | commands = python setup.py test |
786 | |
787 | +[testenv:docs] |
788 | +basepython=python |
789 | +changedir=doc |
790 | +deps=sphinx |
791 | +commands= |
792 | + sphinx-build -b doctest -d {envtmpdir}/doctrees . {envtmpdir}/doctest |
793 | + sphinx-build -W -b html -d {envtmpdir}/doctrees . {envtmpdir}/html |
794 | + |
795 | [testenv:py26-django124] |
796 | basepython = python2.6 |
797 | deps = http://www.djangoproject.com/download/1.2.4/tarball/ |
Discussed via IRC, implemented a couple of very small fixes. Docs look great.