diff --git a/_ext/djangodocs.py b/_ext/djangodocs.py index 6fdd5a2..fd63f2d 100644 --- a/_ext/djangodocs.py +++ b/_ext/djangodocs.py @@ -2,21 +2,32 @@ """ Sphinx plugins for Django documentation. """ +import os +import re -import docutils.nodes -import docutils.transforms -import sphinx -import sphinx.addnodes -import sphinx.builder -import sphinx.directives -import sphinx.environment -import sphinx.htmlwriter +from docutils import nodes, transforms +try: + import json +except ImportError: + try: + import simplejson as json + except ImportError: + try: + from django.utils import simplejson as json + except ImportError: + json = None + +from sphinx import addnodes, roles, __version__ as sphinx_ver +from sphinx.builders.html import StandaloneHTMLBuilder +from sphinx.writers.html import SmartyPantsHTMLTranslator +from sphinx.util.console import bold +from sphinx.util.compat import Directive -def populate_index_to_rebuilds(app, doctree): - app.builder.env.files_to_rebuild['index'] = set([]) +# RE for option descriptions without a '--' prefix +simple_option_desc_re = re.compile( + r'([-_a-zA-Z0-9]+)(\s*.*?)(?=,\s+(?:/|-|--)|$)') def setup(app): - app.connect('doctree-read', populate_index_to_rebuilds) app.add_crossref_type( directivename = "setting", rolename = "setting", @@ -47,79 +58,93 @@ def setup(app): directivename = "django-admin-option", rolename = "djadminopt", indextemplate = u"pair: %s; django-admin コマンドラインオプション", - parse_node = lambda env, sig, signode: sphinx.directives.parse_option_desc(signode, sig), + parse_node = parse_django_adminopt_node, ) - app.add_transform(SuppressBlockquotes) - - # Monkeypatch PickleHTMLBuilder so that it doesn't die in Sphinx 0.4.2 - if sphinx.__version__ == '0.4.2': - monkeypatch_pickle_builder() - -class SuppressBlockquotes(docutils.transforms.Transform): - """ - Remove the default blockquotes that encase indented list, tables, etc. - """ - default_priority = 300 - - suppress_blockquote_child_nodes = ( - docutils.nodes.bullet_list, - docutils.nodes.enumerated_list, - docutils.nodes.definition_list, - docutils.nodes.literal_block, - docutils.nodes.doctest_block, - docutils.nodes.line_block, - docutils.nodes.table - ) - - def apply(self): - for node in self.document.traverse(docutils.nodes.block_quote): - if len(node.children) == 1 and isinstance(node.children[0], self.suppress_blockquote_child_nodes): - node.replace_self(node.children[0]) + app.add_config_value('django_next_version', '0.0', True) + app.add_directive('versionadded', VersionDirective) + app.add_directive('versionchanged', VersionDirective) + app.add_builder(DjangoStandaloneHTMLBuilder) + -class DjangoHTMLTranslator(sphinx.htmlwriter.SmartyPantsHTMLTranslator): +class VersionDirective(Directive): + has_content = True + required_arguments = 1 + optional_arguments = 1 + final_argument_whitespace = True + option_spec = {} + + def run(self): + env = self.state.document.settings.env + arg0 = self.arguments[0] + is_nextversion = env.config.django_next_version == arg0 + ret = [] + node = addnodes.versionmodified() + ret.append(node) + if not is_nextversion: + if len(self.arguments) == 1: + linktext = u'リリースノートを参照してください ' % (arg0) + xrefs = roles.XRefRole()('doc', linktext, linktext, self.lineno, self.state) + node.extend(xrefs[0]) + node['version'] = arg0 + else: + node['version'] = "Development version" + node['type'] = self.name + if len(self.arguments) == 2: + inodes, messages = self.state.inline_text(self.arguments[1], self.lineno+1) + node.extend(inodes) + if self.content: + self.state.nested_parse(self.content, self.content_offset, node) + ret = ret + messages + env.note_versionchange(node['type'], node['version'], node, self.lineno) + return ret + + +class DjangoHTMLTranslator(SmartyPantsHTMLTranslator): """ Django-specific reST to HTML tweaks. """ # Don't use border=1, which docutils does by default. def visit_table(self, node): + self._table_row_index = 0 # Needed by Sphinx self.body.append(self.starttag(node, 'table', CLASS='docutils')) - + # ? Really? def visit_desc_parameterlist(self, node): self.body.append('(') self.first_param = 1 - + self.param_separator = node.child_text_separator + def depart_desc_parameterlist(self, node): self.body.append(')') - pass - - # - # Don't apply smartypants to literal blocks - # - def visit_literal_block(self, node): - self.no_smarty += 1 - sphinx.htmlwriter.SmartyPantsHTMLTranslator.visit_literal_block(self, node) - - def depart_literal_block(self, node): - sphinx.htmlwriter.SmartyPantsHTMLTranslator.depart_literal_block(self, node) - self.no_smarty -= 1 - + + if sphinx_ver < '1.0.8': + # + # Don't apply smartypants to literal blocks + # + def visit_literal_block(self, node): + self.no_smarty += 1 + SmartyPantsHTMLTranslator.visit_literal_block(self, node) + + def depart_literal_block(self, node): + SmartyPantsHTMLTranslator.depart_literal_block(self, node) + self.no_smarty -= 1 + # - # Turn the "new in version" stuff (versoinadded/versionchanged) into a + # Turn the "new in version" stuff (versionadded/versionchanged) into a # better callout -- the Sphinx default is just a little span, # which is a bit less obvious that I'd like. # - # FIXME: these messages are all hardcoded in English. We need to chanage + # FIXME: these messages are all hardcoded in English. We need to change # that to accomodate other language docs, but I can't work out how to make - # that work and I think it'll require Sphinx 0.5 anyway. + # that work. # version_text = { 'deprecated': u'Django %s で撤廃されました', 'versionchanged': u'Django %s で変更されました', 'versionadded': u'Django %s で新たに登場しました', } - + def visit_versionmodified(self, node): self.body.append( self.starttag(node, 'div', CLASS=node['type']) @@ -129,71 +154,77 @@ def visit_versionmodified(self, node): len(node) and ":" or "." ) self.body.append('%s ' % title) - + def depart_versionmodified(self, node): self.body.append("\n") - + # Give each section a unique ID -- nice for custom CSS hooks - # This is different on docutils 0.5 vs. 0.4... - - # The docutils 0.4 override. - if hasattr(sphinx.htmlwriter.SmartyPantsHTMLTranslator, 'start_tag_with_title'): - def start_tag_with_title(self, node, tagname, **atts): - node = { - 'classes': node.get('classes', []), - 'ids': ['s-%s' % i for i in node.get('ids', [])] - } - return self.starttag(node, tagname, **atts) - - # The docutils 0.5 override. - else: - def visit_section(self, node): - old_ids = node.get('ids', []) - node['ids'] = ['s-' + i for i in old_ids] - sphinx.htmlwriter.SmartyPantsHTMLTranslator.visit_section(self, node) - node['ids'] = old_ids + def visit_section(self, node): + old_ids = node.get('ids', []) + node['ids'] = ['s-' + i for i in old_ids] + node['ids'].extend(old_ids) + SmartyPantsHTMLTranslator.visit_section(self, node) + node['ids'] = old_ids def parse_django_admin_node(env, sig, signode): command = sig.split(' ')[0] env._django_curr_admin_command = command title = "django-admin.py %s" % sig - signode += sphinx.addnodes.desc_name(title, title) + signode += addnodes.desc_name(title, title) return sig -def monkeypatch_pickle_builder(): - import shutil - from os import path - try: - import cPickle as pickle - except ImportError: - import pickle - from sphinx.util.console import bold - - def handle_finish(self): - # dump the global context - outfilename = path.join(self.outdir, 'globalcontext.pickle') - f = open(outfilename, 'wb') - try: - pickle.dump(self.globalcontext, f, 2) - finally: - f.close() +def parse_django_adminopt_node(env, sig, signode): + """A copy of sphinx.directives.CmdoptionDesc.parse_signature()""" + from sphinx.domains.std import option_desc_re + count = 0 + firstname = '' + for m in option_desc_re.finditer(sig): + optname, args = m.groups() + if count: + signode += addnodes.desc_addname(', ', ', ') + signode += addnodes.desc_name(optname, optname) + signode += addnodes.desc_addname(args, args) + if not count: + firstname = optname + count += 1 + if not count: + for m in simple_option_desc_re.finditer(sig): + optname, args = m.groups() + if count: + signode += addnodes.desc_addname(', ', ', ') + signode += addnodes.desc_name(optname, optname) + signode += addnodes.desc_addname(args, args) + if not count: + firstname = optname + count += 1 + if not firstname: + raise ValueError + return firstname - self.info(bold('dumping search index...')) - self.indexer.prune(self.env.all_docs) - f = open(path.join(self.outdir, 'searchindex.pickle'), 'wb') - try: - self.indexer.dump(f, 'pickle') - finally: - f.close() - # copy the environment file from the doctree dir to the output dir - # as needed by the web app - shutil.copyfile(path.join(self.doctreedir, sphinx.builder.ENV_PICKLE_FILENAME), - path.join(self.outdir, sphinx.builder.ENV_PICKLE_FILENAME)) +class DjangoStandaloneHTMLBuilder(StandaloneHTMLBuilder): + """ + Subclass to add some extra things we need. + """ - # touch 'last build' file, used by the web application to determine - # when to reload its environment and clear the cache - open(path.join(self.outdir, sphinx.builder.LAST_BUILD_FILENAME), 'w').close() + name = 'djangohtml' - sphinx.builder.PickleHTMLBuilder.handle_finish = handle_finish - + def finish(self): + super(DjangoStandaloneHTMLBuilder, self).finish() + if json is None: + self.warn("cannot create templatebuiltins.js due to missing simplejson dependency") + return + self.info(bold("writing templatebuiltins.js...")) + xrefs = self.env.domaindata["std"]["objects"] + templatebuiltins = { + "ttags": [n for ((t, n), (l, a)) in xrefs.items() + if t == "templatetag" and l == "ref/templates/builtins"], + "tfilters": [n for ((t, n), (l, a)) in xrefs.items() + if t == "templatefilter" and l == "ref/templates/builtins"], + } + outfilename = os.path.join(self.outdir, "templatebuiltins.js") + f = open(outfilename, 'wb') + f.write('var django_template_builtins = ') + json.dump(templatebuiltins, f) + f.write(';\n') + f.close(); diff --git a/_templates/layout.html b/_templates/layout.html index 4ce6827..174cccc 100644 --- a/_templates/layout.html +++ b/_templates/layout.html @@ -1,6 +1,6 @@ {% extends "!layout.html" %} -{%- macro secondnav %} +{%- macro secondnav() %} {%- if prev %} « 前へ {{ reldelim2 }} diff --git a/howto/custom-template-tags.txt b/howto/custom-template-tags.txt index c090c61..dd68037 100644 --- a/howto/custom-template-tags.txt +++ b/howto/custom-template-tags.txt @@ -836,9 +836,6 @@ Python 2.4 からは、デコレータ構文も使えます:: ここでの違いは、 ``do_current_tume()`` がフォーマット文字列と変数名を取り、 ``CurrentTimeNode3`` に渡すという点です。 -Parsing until another block tag -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. _Parsing until another block tag: 他のブロックタグに到達するまでパージングする diff --git a/howto/deployment/index.txt b/howto/deployment/index.txt index 2f84bc9..d6ca9df 100644 --- a/howto/deployment/index.txt +++ b/howto/deployment/index.txt @@ -5,10 +5,10 @@ Django のデプロイ :revision-up-to: 8961 (1.0) -Django's chock-full of shortcuts to make web developer's lives easier, but all -those tools are of no use if you can't easily deploy your sites. Since Django's -inception, ease of deployment has been a major goal. There's a number of good -ways to easily deploy Django: +Django には、ウェブ開発者の負担を軽くするショートカットがぎっしりつまってい +ますが、作ったサイトをデプロイできなければ元も子もありません。 Django プロ +ジェクトの開始当時から、簡単なデプロイは大きな目標の一つでした。Django を簡 +単にデプロイするいい方法はいくつもあります: .. toctree:: :maxdepth: 1 @@ -16,19 +16,19 @@ ways to easily deploy Django: modpython fastcgi -:ref:`Deploying under mod_python ` is the -recommended deployment method; start there if you're not sure which path you'd -like to go down. +デプロイの方法としては、 :ref:`mod_python を使う方法 +` をお勧めします。どの方法を選んでよいのか分か +らない場合は、 mod_python を使いましょう。 .. seealso:: - * `Chapter 20 of The Django Book`_ discusses deployment and especially - scaling in more detail. + * `Django Book の 20 章 `_ では、デプロイ + 方法と、とりわけデプロイ時のスケーリングについて詳しく解説しています。 - * `mod_wsgi`_ is a newcomer to the Python deployment world, but it's rapidly - gaining traction. Currently there's a few hoops you have to jump through to - `use mod_wsgi with Django`_, but mod_wsgi tends to get rave reviews from - those who use it. + * `mod_wsgi`_ はまだ新参のデプロイ手段ですが、急速に人々を惹き付けつつ + あります。今のところ、 + `mod_wsgi で Django を動かす `_ には、いく + つかステップが必要ですが、ユーザの評判は上々のようです。 .. _chapter 20 of the django book: http://djangobook.com/en/1.0/chapter20/ .. _mod_wsgi: http://code.google.com/p/modwsgi/ diff --git a/internals/documentation.txt b/internals/documentation.txt index 05d1304..9d59b80 100644 --- a/internals/documentation.txt +++ b/internals/documentation.txt @@ -1,206 +1,215 @@ .. _internals-documentation: -How the Django documentation works -================================== +Django ドキュメントの仕組み +============================ :revision-up-to: 8961 (1.0) -\... and how to contribute. +\... と、ドキュメント作業への貢献方法 -Django's documentation uses the Sphinx__ documentation system, which in turn is -based on docutils__. The basic idea is that lightly-formatted plain-text -documentation is transformed into HTML, PDF, and any other output format. +Django のドキュメントは Sphinx__ ドキュメンテーションシステムを使っています。 +Sphinx は docutils__ に基づいて作られています。 docutils は、簡単な書式の +プレーンテキストを、 HTML や PDF その他の様々な出力形式で簡単に扱えるように +することを念頭に置いて作られています。 __ http://sphinx.pocoo.org/ __ http://docutils.sf.net/ -To actually build the documentation locally, you'll currently need to install -Sphinx -- ``easy_install Sphinx`` should do the trick. +ドキュメントを実際に手元でビルドするには、現状では Sphinx をインストールす +る必要があります。インストールは ``easy_install Sphinx`` でできます。 -Then, building the html is easy; just ``make html`` from the ``docs`` directory. +さて、 html のビルドは簡単です。単に ``docs`` ディレクトリで ``make html`` +を実行するだけです。 -To get started contributing, you'll want to read the `ReStructuredText -Primer`__. After that, you'll want to read about the `Sphinx-specific markup`__ -that's used to manage metadata, indexing, and cross-references. +ドキュメント作業に貢献したいなら、まず `ReStructuredText Primer`__ を読みま +しょう。その後 `Sphinx 固有のマークアップ`__ の説明を読んで、メタデータやイ +ンデクス、相互参照の方法を学ぶとよいでしょう。 __ http://sphinx.pocoo.org/rest.html __ http://sphinx.pocoo.org/markup/ -The main thing to keep in mind as you write and edit docs is that the more -semantic markup you can add the better. So:: +ドキュメントを書いたり編集したりする上で覚えておかねばならないのは、よりセ +マンティックなマークアップを使う方がよい、ということです。従って:: Add ``django.contrib.auth`` to your ``INSTALLED_APPS``... - -Isn't nearly as helpful as:: + +とするよりも:: Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`... - -This is because Sphinx will generate proper links for the later, which greatly -helps readers. There's basically no limit to the amount of useful markup you can -add. -Django-specific markup ----------------------- +と書いた方が便利なのです。なぜなら、後者のマークアップの場合、 Sphinx が適 +切なリンクを生成するため、ドキュメントの読み手にとって非常に助かるからです。 +制限はありません。可能な限り便利なマークアップを使ってください。 -Besides the `Sphinx built-in markup`__, Django's docs defines some extra description units: +Django 固有のマークアップ +-------------------------- + +`Sphinx の組み込みマークアップ`__ の他に、Django ドキュメントではいくつか追 +加で表記単位 (description unit) を定義しています: __ http://sphinx.pocoo.org/markup/desc.html - * Settings:: + * 設定:: .. setting:: INSTALLED_APPS - To link to a setting, use ``:setting:`INSTALLED_APPS```. + リンクするには、 ``:setting:`INSTALLED_APPS``` としてください。 - * Template tags:: + * テンプレートタグ:: .. templatetag:: regroup - To link, use ``:ttag:`regroup```. + タグの説明にリンクするには ``:ttag:`regroup``` としてください。 - * Template filters:: + * テンプレートフィルタ:: .. templatefilter:: linebreaksbr - To link, use ``:tfilter:`linebreaksbr```. + リンクするには ``:tfilter:`linebreaksbr``` としてください。 - * Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``):: + * フィールド照合 (``Foo.objects.filter(bar__exact=whatever)`` など):: .. fieldlookup:: exact - To link, use ``:lookup:`exact```. + リンクするには ``:lookup:`exact``` としてください。 - * ``django-admin`` commands:: + * ``django-admin`` コマンド:: .. django-admin:: syncdb - To link, use ``:djadmin:`syncdb```. + リンクするには ``:djadmin:`syncdb``` としてください。 - * ``django-admin`` command-line options:: + * ``django-admin`` コマンドラインオプション:: .. django-admin-option:: --traceback - To link, use ``:djadminopt:`--traceback```. + リンクするには ``:djadminopt:`--traceback``` としてください。 -An example ----------- +例 +---- -For a quick example of how it all fits together, check this out: +マークアップの簡単な例を以下にまとめました: - * First, the ``ref/settings.txt`` document starts out like this:: + * まず、 ``ref/settings.txt`` ドキュメントを見てみましょう。このドキュ + メントは以下のような内容から始まっています:: .. _ref-settings: - Available settings - ================== + settings に設定できる値 + ========================== ... - * Next, if you look at the ``topics/settings.txt`` document, you can see how - a link to ``ref/settings`` works:: + * ``topics/settings.txt`` ドキュメントを見ると、 ``ref/settings`` への + リンクがどのように書かれているか分かります:: - Available settings - ================== + 利用可能な設定 + ============== - For a full list of available settings, see the :ref:`settings reference - `. + 利用可能な設定は :ref:`setting リファレンス ` を参照 + してください。 - * Next, notice how the settings (right now just the top few) are annotated:: + * 設定項目をどのように表記しているかを見てみましょう:: .. setting:: ADMIN_FOR ADMIN_FOR - --------- - - Default: ``()`` (Empty tuple) - - Used for admin-site settings modules, this should be a tuple of settings - modules (in the format ``'foo.bar.baz'``) for which this site is an - admin. + --------- - The admin site uses this in its automatically-introspected - documentation of models, views and template tags. + デフォルト値: ``()`` (空のタプル) + admin 用サイトの設定モジュールで設定します。このサイトの admin を他 + のサイトの admin にする場合、設定モジュールを (``'foo.bar.baz'`` の + 形式のタプルで) 指定します。 - This marks up the following header as the "canonical" target for the - setting ``ADMIN_FOR`` This means any time I talk about ``ADMIN_FOR``, I - can reference it using ``:setting:`ADMIN_FOR```. - -That's basically how everything fits together. + admin サイトはこの変数を使って、モデルやビュー、テンプレートタグの + ドキュメントに対するイントロスペクションを自動的に行います。 + + この ``.. settings::`` の部分で、 ``ADMIN_FOR`` の「正しい」ターゲッ + トとしてを定義しています。これで、 ``ADMIN_FOR`` について説明するとき + に、 ``:setting:`ADMIN_FOR``` を使って参照できます。 + +このようにして、お互いの参照を解決します。 TODO ---- -The work is mostly done, but here's what's left, in rough order of priority. +ドキュメントの整備はほぼ終っていますが、まだ、ほぼ以降に挙げる順番にやらね +ばならないことが残っています。 - * Fix up generic view docs: adapt Chapter 9 of the Django Book (consider - this TODO item my permission and license) into - ``topics/generic-views.txt``; remove the intro material from - ``ref/generic-views.txt`` and just leave the function reference. + * 汎用ビューの部分を修正します。 Django Book の 9 章を + ``topics/generic-views.txt`` にもってきて (この項目をもって、著者の許 + 可とライセンス許諾に代えます)、 ``ref/generic-views.txt`` の導入部分 + を削除し、関数のリファレンスだけにします。 - * Change the "Added/changed in development version" callouts to proper - Sphinx ``.. versionadded::`` or ``.. versionchanged::`` directives. + * 「開発版で追加／変更された機能」の部分を、全て Sphinx の + ``.. versionadded::`` および ``.. versionchanged::`` ディレクティブに + 置き換えます。 - * Check for and fix malformed links. Do this by running ``make linkcheck`` - and fix all of the 300+ errors/warnings. + * おかしなリンクをチェックして修正します。 ``make linkcheck`` を実行し + て、 300 個以上出るエラーや警告メッセージを全て修正します。 - In particular, look at all the relative links; these need to be - changed to proper references. + 特に、相対リンクを全て調べる必要があります。これらは正しい参照に変更 + せねばなりません。 - * Most of the various ``index.txt`` documents have *very* short or even - non-existent intro text. Each of those documents needs a good short intro - the content below that point. + * ほとんどの ``index.txt`` ドキュメントに、肝心の説明文が *とても* わず + かしかないか、まったくありません。それぞれに、各階層下に収められてい + るコンテンツのよい説明文が必要です。 - * The glossary is very perfunctory. It needs to be filled out. + * 用語集がいい加減すぎます。もっと内容を濃くする必要があります。 - * Add more metadata targets: there's lots of places that look like:: + * メタデータターゲットをもっと増やします。まだ:: ``File.close()`` ~~~~~~~~~~~~~~~~ - \... these should be:: + のような部分がたくさんあり、以下のように書き直さねばなりません:: .. method:: File.close() - That is, use metadata instead of titles. + つまり、タイトルではなくメタデータを使わねばなりません。 - * Add more links -- nearly everything that's an inline code literal - right now can probably be turned into a xref. + * リンクを追加します。現状のインラインコードリテラルは、ほぼ全て相互参 + 照に変更できます。 - See the ``literals_to_xrefs.py`` file in ``_ext`` -- it's a shell script - to help do this work. + ``_ext`` 以下にある ``literals_to_xrefs.py`` ファイルを参照してくださ + い。このシェルスクリプトを使えば、作業が楽になります。 - This will probably be a continuing, never-ending project. + おそらく終らない、地道な作業になるでしょう。 - * Add `info field lists`__ where appropriate. + * 適切な `info フィールドリスト`__ を追加する必要があります。 __ http://sphinx.pocoo.org/markup/desc.html#info-field-lists - * Add ``.. code-block:: `` to literal blocks so that they get - highlighted. + * 色づけ表示の必要なリテラルブロックに ``.. code-block:: `` を付 + 加する必要があります。 -Hints ------ +ヒント +------- -Some hints for making things look/read better: +読みやすいドキュメントにするためのヒントをいくつか紹介しましょう: - * Whenever possible, use links. So, use ``:setting:`ADMIN_FOR``` instead of - ````ADMIN_FOR````. + * 可能なかぎり、リンクを使いましょう。例えば、 ````ADMIN_FOR```` は + ``:setting:`ADMIN_FOR``` にしましょう。 - * Some directives (``.. setting::``, for one) are prefix-style directives; - they go *before* the unit they're describing. These are known as - "crossref" directives. Others (``.. class::``, e.g.) generate their own - markup; these should go inside the section they're describing. These are - called "description units". + * ディレクティブの中には、プレフィクススタイルのもの (``.. setting::`` + など)あります。プレフィクススタイルのディレクティブは、記述対象のブロッ + クの *前* に置かねばなりません。その他 (``.. class::`` など) は独自の + マークアップを生成します。その他のディレクティブは、記述対象のセクショ + ンの中に置かねばなりません。こうしたディレクティブは「記述単位 + (description unit)」と呼びます。 - You can tell which are which by looking at in :file:`_ext/djangodocs.py`; - it registers roles as one of the other. + どのディレクティブがどちらのタイプは、 :file:`_ext/djangodocs.py` を + 参照してください。このファイルの中で、それぞれのロールを登録していま + す。 - * When referring to classes/functions/modules, etc., you'll want to use the - fully-qualified name of the target - (``:class:`django.contrib.contenttypes.models.ContentType```). + * クラスや関数、モジュールなどを参照するときは、完全指定の名前 + (``:class:`django.contrib.contenttypes.models.ContentType```)を使うと + よいでしょう。 - Since this doesn't look all that awesome in the output -- it shows the - entire path to the object -- you can prefix the target with a ``~`` - (that's a tilde) to get just the "last bit" of that path. So - ``:class:`~django.contrib.contenttypes.models.ContentType``` will just - display a link with the title "ContentType". + 完全指定の名前を使っただけでは、出力はさほどきれいにならないでしょう。 + というのも、オブジェクトの全てのパスが表示されてしまうからです。 + ターゲットの先頭にチルダ (``~``) を付けると、パスの「最後の部分」だけ + が表示されます。従って、 + ``:class:`~django.contrib.contenttypes.models.ContentType``` とすると、 + 単に "ContentType" と書かれたリンクを生成します。 + diff --git a/misc/api-stability.txt b/misc/api-stability.txt index c4233aa..82658c6 100644 --- a/misc/api-stability.txt +++ b/misc/api-stability.txt @@ -121,19 +121,22 @@ APIの安定性とは コントリビュートアプリケーション (``django.contrib``) ---------------------------------------------------------- -While we'll make every effort to keep these APIs stable -- and have no plans to -break any contrib apps -- this is an area that will have more flux between -releases. As the web evolves, Django must evolve with it. - -However, any changes to contrib apps will come with an important guarantee: -we'll make sure it's always possible to use an older version of a contrib app if -we need to make changes. Thus, if Django 1.5 ships with a backwards-incompatible -``django.contrib.flatpages``, we'll make sure you can still use the Django 1.4 -version alongside Django 1.5. This will continue to allow for easy upgrades. - -Historically, apps in ``django.contrib`` have been more stable than the core, so -in practice we probably won't have to ever make this exception. However, it's -worth noting if you're building apps that depend on ``django.contrib``. +私達は API を安定に保とうとあらゆる努力を注いでおり、現状では contrib のア +プリケーションを変更するつもりはありませんが、 contrib はリリース間で変更さ +れやすい分野ではあります。ウェブが進化すれば、Django もそれに合わせて進化せ +ねばならないからです。 + +とはいえ、 contrib のアプリケーションの変更について保証していることがありま +す。まず、 contrib のアプリケーションに変更を行う必要があった場合、古いバー +ジョンのアプリケーションも使えるようにします。すなわち、仮に Django 1.5 で +以前のバージョンと互換性のない ``django.contrib.flatpages`` を出した場合、 +Django 1.4 版の ``django.contrib.flatpages`` も Django 1.5 で使えるようにし +ます。この措置によって、アップグレードを容易にします。 + +歴史的に、これまで ``django.contrib`` のアプリケーションはコア部分よりも安 +定でした。したがって、おそらく上記のような例外的なことは起きないでしょう。 +とはいえ、 ``django.contrib`` に依存してアプリケーションを開発しているなら、 +覚えておくにこしたことはありません。 .. _APIs marked as internal: diff --git a/ref/contrib/humanize.txt b/ref/contrib/humanize.txt index b5e8417..2143c0a 100644 --- a/ref/contrib/humanize.txt +++ b/ref/contrib/humanize.txt @@ -7,8 +7,7 @@ django.contrib.humanize :revision-up-to: 8961 (1.0) .. module:: django.contrib.humanize - :synopsis: A set of Django template filters useful for adding a "human - touch" to data. + :synopsis: データを「人間くさく」表示するためのテンプレートフィルタです。 humanize は、データに「人間くささ (human touch)」を与えるための Django テン プレートフィルタです。 diff --git a/ref/settings.txt b/ref/settings.txt index a322876..09a971d 100644 --- a/ref/settings.txt +++ b/ref/settings.txt @@ -1,7 +1,7 @@ .. _ref-settings: -Available settings -================== +settings に設定できる値 +========================== :revision-up-to: 8961 (1.0) diff --git a/topics/auth.txt b/topics/auth.txt index 31d1267..26a8a81 100644 --- a/topics/auth.txt +++ b/topics/auth.txt @@ -69,7 +69,8 @@ API リファレンス .. class:: models.User - :class:`~django.contrib.auth.models.User` objects have the following fields: + :class:`~django.contrib.auth.models.User` オブジェクトには以下のフィー + ルドがあります: .. attribute:: models.User.username diff --git a/topics/forms/modelforms.txt b/topics/forms/modelforms.txt index 30ee7d6..5340922 100644 --- a/topics/forms/modelforms.txt +++ b/topics/forms/modelforms.txt @@ -602,18 +602,19 @@ clean() メソッドのオーバライド >>> formset = BookFormSet(instance=author) -More than one foriegn key to the same model -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +同じモデルに対して複数の外部キーを張っている場合 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If your model contains more than one foreign key to the same model you will -need to resolve the ambiguity manually using ``fk_name``. Given the following -model:: +同じモデルに対する複数の外部キーを張っている場合、キー間のあいまいさを無く +すために、 ``fk_name`` を手動で設定する必要があります。以下のモデルを例に考 +えてみましょう:: class Friendship(models.Model): from_friend = models.ForeignKey(Friend) to_friend = models.ForeignKey(Friend) length_in_months = models.IntegerField() -To resolve this you can simply use ``fk_name`` to ``inlineformset_factory``:: +このモデルの問題を解決するには、 ``fk_name`` を ``inlineformset_factory`` +に設定してください:: >>> FrienshipFormSet = inlineformset_factory(Friend, Friendship, fk_name="from_friend") diff --git a/topics/testing.txt b/topics/testing.txt index 081d653..d4b82ff 100644 --- a/topics/testing.txt +++ b/topics/testing.txt @@ -1161,11 +1161,11 @@ TestCase 内の各テストケースの開始時点で抹消されます。手 ``False`` にする場合、テストスイートは手動操作なしで実行できねばなりま せん。 - ``extra_tests`` には、このテストランナに追加で実行させたい ``TestCase`` - インスタンスを指定します。 ``extra_tests`` を指定すると、 ``module_list`` - から発見したテストに加えて、指定したテストを実行します。 + ``extra_tests`` には、このテストランナに追加で実行させたい ``TestCase`` + インスタンスを指定します。 ``extra_tests`` を指定すると、 + ``module_list`` から発見したテストに加えて、指定したテストを実行します。 - このメソッドは失敗したテストの数を返さねばなりません。 + このメソッドは失敗したテストの数を返さねばなりません。 .. _Testing utilities: