From 72486b77b10c806a715f82b53abb833853d47952 Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Thu, 4 Oct 2012 18:38:59 -0400 Subject: [PATCH 1/3] More cross linking cleanup fixing intersphinx links --- .../use-cases/metadata-and-asset-management.txt | 5 +++-- source/use-cases/product-catalog.txt | 17 ++++++++++------- source/use-cases/storing-log-data.txt | 10 ++++++---- 3 files changed, 19 insertions(+), 13 deletions(-) diff --git a/source/use-cases/metadata-and-asset-management.txt b/source/use-cases/metadata-and-asset-management.txt index 9c7599c9057..31241e58d11 100644 --- a/source/use-cases/metadata-and-asset-management.txt +++ b/source/use-cases/metadata-and-asset-management.txt @@ -150,7 +150,8 @@ Procedure ````````` The most common operations inside of a CMS center on creating and -editing content. Consider the following :py:meth:`` +editing content. Consider the following +:py:meth:`insert() ` operation: .. code-block:: python @@ -265,7 +266,7 @@ upon the basic update procedure: Because uploading the photo spans multiple documents and is a non-atomic operation, you must "lock" the file during upload by -writing :py:class:`datetime.utcnow() ` in the +writing :py:meth:`datetime.utcnow() ` in the record. This helps when there are multiple concurrent editors and lets the application detect stalled file uploads. This operation assumes that, for photo upload, the last update will succeed: diff --git a/source/use-cases/product-catalog.txt b/source/use-cases/product-catalog.txt index 0db11551d73..897245227db 100644 --- a/source/use-cases/product-catalog.txt +++ b/source/use-cases/product-catalog.txt @@ -525,24 +525,27 @@ per-connection or per-operation basis. In :api:`PyMongo `, set the :py:attr:`read_preference ` argument. -The :py:class:`SECONDARY ` property in -the following example, permits reads from a :term:`secondary` (as well -as a primary) for the entire connection . +The +:py:attr:`SECONDARY ` +property in the following example, permits reads from a +:term:`secondary` (as well as a primary) for the entire connection . .. code-block:: python conn = pymongo.Connection(read_preference=pymongo.SECONDARY) -Conversely, the :py:class:`SECONDARY_ONLY -` read preference means that the +Conversely, the +:py:attr:`SECONDARY_ONLY ` +read preference means that the client will only send read operation only to the secondary member .. code-block:: python conn = pymongo.Connection(read_preference=pymongo.SECONDARY_ONLY) -You can also specify :py:attr:`read_preference -` for specific queries, +You can also specify +:py:attr:`read_preference ` +for specific queries, as follows: .. code-block:: python diff --git a/source/use-cases/storing-log-data.txt b/source/use-cases/storing-log-data.txt index c5c7dc2a118..9033c887bb9 100644 --- a/source/use-cases/storing-log-data.txt +++ b/source/use-cases/storing-log-data.txt @@ -409,7 +409,8 @@ following command: >>> db.events.ensure_index([('time', 1), ('host', 1)]) To analyze the performance for the above query using this index, issue -the :py:meth:`q_events.explain() ` +the +:py:meth:`q_events.explain() ` method in a Python console. This will return something that resembles: .. code-block:: pycon @@ -437,7 +438,8 @@ index using the following operation: >>> db.events.ensure_index([('host', 1), ('time', 1)]) -Use the :py:meth:`q_events.explain() ` +Use the +:py:meth:`q_events.explain() ` operation to test the performance: .. code-block:: pycon @@ -489,9 +491,9 @@ Aggregation The :term:`aggregation framework` provides the capacity for queries that select, process, and aggregate results from large numbers of -documents. The :method:`aggregate()` (and :dbcommand:`aggregate` +documents. The :method:`aggregate() ` (and :dbcommand:`aggregate` :term:`command `) offers greater flexibility, -capacity with less complexity than the existing :dbcommand:`mapreduce` +capacity with less complexity than the existing :dbcommand:`mapReduce ` and :dbcommand:`group` aggregation. Consider the following aggregation :term:`pipeline`: [#sql-aggregation-equivalents]_ From 3b1b9e97e63c65390018d5ee72d9c6f29cb76ccc Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Fri, 5 Oct 2012 10:06:32 -0400 Subject: [PATCH 2/3] add nitpick option to makefile, add intersphinx mappings to conf.py --- conf.py | 5 ++++- makefile | 7 +++++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/conf.py b/conf.py index 2c5a4d66c4d..e6d68320718 100644 --- a/conf.py +++ b/conf.py @@ -97,7 +97,10 @@ 'hardlink' : ( 'http://docs.mongodb.org/' + current_git_branch + '/%s', '') } -intersphinx_mapping = {'pymongo': ('http://api.mongodb.org/python/current/', None)} +intersphinx_mapping = { + 'pymongo': ('http://api.mongodb.org/python/current/', None), + 'python' : ('http://docs.python.org/', None) + } # -- Options for HTML output --------------------------------------------------- diff --git a/makefile b/makefile index 55d059c6358..db093f3a1b4 100644 --- a/makefile +++ b/makefile @@ -35,6 +35,13 @@ endif # Sphinx variables. SPHINXOPTS = -c ./ SPHINXBUILD = sphinx-build + +ifdef NITPICK +timestamp := $(shell date +%Y%m%d%H%M) +SPHINXOPTS += -n +SPHINXOPTS += -w $(branch-output)/build.$(timestamp).log +endif + PAPER = letter PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter From e0304d0a5b08b5dd1678c211c8c16b6f7c7d2ee9 Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Fri, 5 Oct 2012 17:40:43 -0400 Subject: [PATCH 3/3] DOCS-576 additional linking fixes --- conf.py | 5 ++- ...application-with-django-mongodb-engine.txt | 36 +++++++++---------- 2 files changed, 22 insertions(+), 19 deletions(-) diff --git a/conf.py b/conf.py index e6d68320718..e815425fdad 100644 --- a/conf.py +++ b/conf.py @@ -99,7 +99,10 @@ intersphinx_mapping = { 'pymongo': ('http://api.mongodb.org/python/current/', None), - 'python' : ('http://docs.python.org/', None) + 'python' : ('http://docs.python.org/', None), + 'django': ('https://django.readthedocs.org/en/latest/',None), + 'djangomongodbengine': ('http://django-mongodb.org/',None), + 'djangotoolbox' : ('http://djangotoolbox.readthedocs.org/en/latest/', None), } # -- Options for HTML output --------------------------------------------------- diff --git a/source/tutorial/write-a-tumblelog-application-with-django-mongodb-engine.txt b/source/tutorial/write-a-tumblelog-application-with-django-mongodb-engine.txt index da115fc6a77..049c6e66365 100644 --- a/source/tutorial/write-a-tumblelog-application-with-django-mongodb-engine.txt +++ b/source/tutorial/write-a-tumblelog-application-with-django-mongodb-engine.txt @@ -28,7 +28,7 @@ have a basic familiarity with MongoDB operation and have .. note:: - `Django MongoDB Engine`_ uses the a forked version of Django 1.3 + `Django MongoDB Engine`_ uses a forked version of Django 1.3 that adds non-relational support. .. _Django: http://www.djangoproject.com @@ -47,7 +47,7 @@ Prerequisite This tutorial uses pip_ to install packages and virtualenv_ to isolate Python environments. While these tools and this configuration are not required as such, they ensure a standard environment and are strongly -recommended. Issue the following command at the system prompt: +recommended. Issue the following commands at the system prompt: .. code-block:: sh @@ -59,7 +59,7 @@ Respectively, these commands: install the ``virtualenv`` program project (named ``myproject``.) To activate ``myproject`` environment at the system prompt, use the -following command: +following commands: .. code-block:: bash @@ -133,7 +133,7 @@ The first step in writing a tumblelog in `Django`_ is to define the "models" or in MongoDB's terminology :term:`documents `. In this application, you will define posts and comments, so that each -:py:class:`Post` can contain a list of :py:class:`Comments`. Edit the +``Post`` can contain a list of ``Comments``. Edit the :file:`tumblelog/models.py` file so it resembles the following: .. code-block:: python @@ -167,17 +167,17 @@ In this application, you will define posts and comments, so that each author = models.CharField(verbose_name="Name", max_length=255) -The Django "nonrel" code looks the same as vanilla Django however, +The Django "nonrel" code looks the same as vanilla Django, however there is no built in support for some of MongoDB's native data types -like Lists and Embedded data. :py:mod:`djangotoolbox` handles these +like Lists and Embedded data. :py:mod:`djangotoolbox:djangotoolbox` handles these definitions. .. see:: The Django MongoDB Engine fields_ documentation for more. -The models declare an index to :py:class:`Post`. One for the -:py:obj:`created_at` date as our frontpage will order by date: there -is no need to add :py:obj:`db_index` on :py:obj:`SlugField` because -there is a default index on :py:obj:`SlugField`. +The models declare an index to the ``Post`` class. One for the +``created_at`` date as our frontpage will order by date: there +is no need to add ``db_index`` on ``SlugField`` because +there is a default index on ``SlugField``. .. _fields: http://django-mongodb.org/reference/fields.html @@ -268,7 +268,7 @@ and :file:`templates/tumblelog` for storing the tumblelog templates: mkdir -p templates/tumblelog Configure Django so it can find the templates by updating -:py:obj:`TEMPLATE_DIRS` in the :file:`settings.py` file to the +``TEMPLATE_DIRS`` in the :file:`settings.py` file to the following: .. code-block:: python @@ -441,7 +441,7 @@ the following to the :file:`views.py` file: .. note:: - :py:class:`PostDetailView` extends the :py:class:`DetailView` so + The ``PostDetailView`` class extends the ``DetailView`` class so that it can handle ``GET`` and ``POST`` requests. On ``POST``, :py:func:`post` validates the comment: if valid, :py:func:`post` appends the comment to the post. @@ -511,19 +511,19 @@ can easily create an administrative interface for posts with Django. Enable the admin by adding the following apps to :py:obj:`INSTALLED_APPS` in :file:`settings.py`. -- :py:mod:`django.contrib.admin` -- :py:mod:`django_mongodb_engine` -- :py:mod:`djangotoolbox` +- :py:mod:`django:django.contrib.admin` +- :py:mod:`djangomongodbengine` +- :py:mod:`djangotoolbox:djangotoolbox` - :py:mod:`tumblelog` .. warning:: This application does not require the :py:class:`Sites` - framework. As a result, remove :py:mod:`django.contrib.sites` from + framework. As a result, remove :py:mod:`django:django.contrib.sites` from :py:obj:`INSTALLED_APPS`. If you need it later please read `SITE_ID issues`_ document. -Create a :file:`admin.py` file and register the :py:class:`Post` model +Create a :file:`admin.py` file and register the ``Post`` model with the admin app: .. code-block:: python @@ -536,7 +536,7 @@ with the admin app: .. note:: The above modifications deviate from the default django-nonrel_ and - :py:mod:`djangotoolbox` mode of operation. Django's administration + :py:mod:`djangotoolbox:djangotoolbox` mode of operation. Django's administration module will not work unless you exclude the ``comments`` field. By making the ``comments`` field non-editable in the "admin" model definition, you will allow the administrative interface to function.