From e2040e8842721d32a3eb122933a4cf60199a4a52 Mon Sep 17 00:00:00 2001 From: Matt Westcott Date: Fri, 4 Jul 2014 21:57:58 +0100 Subject: [PATCH] fix documentation syntax errors / warnings --- docs/building_your_site/frontenddevelopers.rst | 6 ++++-- docs/editing_api.rst | 10 ++++++---- .../documents_images_snippets/index.rst | 1 + .../documents_images_snippets/snippets.rst | 3 +++ docs/frontend_cache_purging.rst | 2 ++ docs/gettingstarted.rst | 12 ++++++------ docs/index.rst | 2 ++ docs/management_commands.rst | 4 ++-- docs/settings.rst | 14 +++----------- docs/sitemap_generation.rst | 2 ++ docs/wagtail_search.rst | 2 +- 11 files changed, 32 insertions(+), 26 deletions(-) diff --git a/docs/building_your_site/frontenddevelopers.rst b/docs/building_your_site/frontenddevelopers.rst index 35aa1c84509..a3ba8eaa2a2 100644 --- a/docs/building_your_site/frontenddevelopers.rst +++ b/docs/building_your_site/frontenddevelopers.rst @@ -192,9 +192,10 @@ More control over the ``img`` tag Wagtail provides two shorcuts to give greater control over the ``img`` element: -.. versionadded:: 0.4 **Adding attributes to the {% image %} tag** +.. versionadded:: 0.4 + Extra attributes can be specified with the syntax ``attribute="value"``: .. code-block:: django @@ -215,10 +216,11 @@ Wagtail can assign the image data to another object using Django's ``as`` syntax {{ tmp_photo.alt }} -.. versionadded:: 0.4 The ``attrs`` shortcut ----------------------- +.. versionadded:: 0.4 + You can also use the ``attrs`` property as a shorthand to output the ``src``, ``width``, ``height`` and ``alt`` attributes in one go: .. code-block:: django diff --git a/docs/editing_api.rst b/docs/editing_api.rst index 5113eb3b89e..a12d883d324 100644 --- a/docs/editing_api.rst +++ b/docs/editing_api.rst @@ -1,6 +1,6 @@ Defining models with the Editing API -=========== +==================================== .. note:: This documentation is currently being written. @@ -251,7 +251,7 @@ Field Customization By adding CSS classnames to your panel definitions or adding extra parameters to your field definitions, you can control much of how your fields will display in the Wagtail page editing interface. Wagtail's page editing interface takes much of its behavior from Django's admin, so you may find many options for customization covered there. (See `Django model field reference`_ ). -.. _Django model field reference:https://docs.djangoproject.com/en/dev/ref/models/fields/ +.. _Django model field reference: https://docs.djangoproject.com/en/dev/ref/models/fields/ Full-Width Input @@ -374,7 +374,7 @@ For more on ``django-modelcluster``, visit `the django-modelcluster github proje Extending the WYSIWYG Editor (hallo.js) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To inject javascript into the Wagtail page editor, see the :ref:`insert_editor_js` hook. Once you have the hook in place and your hallo.js plugin loads into the Wagtail page editor, use the following Javascript to register the plugin with hallo.js. +To inject javascript into the Wagtail page editor, see the :ref:`insert_editor_js ` hook. Once you have the hook in place and your hallo.js plugin loads into the Wagtail page editor, use the following Javascript to register the plugin with hallo.js. .. code-block:: javascript @@ -565,7 +565,8 @@ Where ``'hook'`` is one of the following hook strings and ``function`` is a func .. _construct_whitelister_element_rules: ``construct_whitelister_element_rules`` - .. versionadded:: 0.4 +.. versionadded:: 0.4 + Customise the rules that define which HTML elements are allowed in rich text areas. By default only a limited set of HTML elements and attributes are whitelisted - all others are stripped out. The callables passed into this hook must return a dict, which maps element names to handler functions that will perform some kind of manipulation of the element. These handler functions receive the element as a `BeautifulSoup `_ Tag object. The ``wagtail.wagtailcore.whitelist`` module provides a few helper functions to assist in defining these handlers: ``allow_without_attributes``, a handler which preserves the element but strips out all of its attributes, and ``attribute_rule`` which accepts a dict specifying how to handle each attribute, and returns a handler function. This dict will map attribute names to either True (indicating that the attribute should be kept), False (indicating that it should be dropped), or a callable (which takes the initial attribute value and returns either a final value for the attribute, or None to drop the attribute). @@ -593,6 +594,7 @@ On loading, Wagtail will search for any app with the file ``image_formats.py`` a As an example, add a "thumbnail" format: .. code-block:: python + # image_formats.py from wagtail.wagtailimages.formats import Format, register_image_format diff --git a/docs/editor_manual/documents_images_snippets/index.rst b/docs/editor_manual/documents_images_snippets/index.rst index 13ceb039e63..35817aa79d3 100644 --- a/docs/editor_manual/documents_images_snippets/index.rst +++ b/docs/editor_manual/documents_images_snippets/index.rst @@ -10,3 +10,4 @@ Wagtail allows you to manage all of your documents and images through their own documents images + snippets diff --git a/docs/editor_manual/documents_images_snippets/snippets.rst b/docs/editor_manual/documents_images_snippets/snippets.rst index dd9fbccc013..0dfa1fdad4c 100644 --- a/docs/editor_manual/documents_images_snippets/snippets.rst +++ b/docs/editor_manual/documents_images_snippets/snippets.rst @@ -1,6 +1,9 @@ Snippets ~~~~~~~~ +.. note:: + Documentation currently incomplete and in draft status + .. UNSURE HOW TO WRITE THIS AS THE ADVERT EXAMPLE IN WAGTAIL DEMO IS NOT A PARTICULARLY HELPFUL USE CASE. When creating a page on a website, it is a common occurance to want to add in a piece of content that already exists on another page. An example of this would be a person's contact details, or an advert that you want to simply show on every page of your site, without having to manually apply it. diff --git a/docs/frontend_cache_purging.rst b/docs/frontend_cache_purging.rst index 34a6fda50bd..c1b03624fa8 100644 --- a/docs/frontend_cache_purging.rst +++ b/docs/frontend_cache_purging.rst @@ -1,3 +1,5 @@ +.. _frontend_cache_purging: + Frontend cache purging ====================== diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index de635256c95..04905700e8c 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -40,7 +40,7 @@ Once you've experimented with the demo app and are ready to build your pages via On OS X ~~~~~~~ -Install `pip `_ and `virtualenvwrapper `_ if you don't have them already. Then, in your terminal:: +Install `pip `__ and `virtualenvwrapper `_ if you don't have them already. Then, in your terminal:: mkvirtualenv wagtaildemo git clone https://github.com/torchbox/wagtaildemo.git @@ -75,10 +75,10 @@ Wagtail instance available as the basis for your new site: ./manage.py runserver 0.0.0.0:8000 - This will make the app accessible on the host machine as -`localhost:8111 `_ - you can access the Wagtail admin -interface at `localhost:8111/admin `_. The codebase -is located on the host machine, exported to the VM as a shared folder; code -editing and Git operations will generally be done on the host. + `localhost:8111 `_ - you can access the Wagtail admin + interface at `localhost:8111/admin `_. The codebase + is located on the host machine, exported to the VM as a shared folder; code + editing and Git operations will generally be done on the host. Using Docker ~~~~~~~~~~~~ @@ -101,7 +101,7 @@ use the following steps: Required dependencies ===================== -- `pip `_ +- `pip `__ - `libjpeg `_ - `libxml2 `_ - `libxslt `_ diff --git a/docs/index.rst b/docs/index.rst index ae2300556b8..d200f2bc1d5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,6 +20,8 @@ It supports Django 1.6.2+ on Python 2.6, 2.7, 3.2, 3.3 and 3.4. Django 1.7 suppo deploying performance static_site_generation + frontend_cache_purging + sitemap_generation management_commands contributing support diff --git a/docs/management_commands.rst b/docs/management_commands.rst index 3f77fc3eff6..96cfe95c3a7 100644 --- a/docs/management_commands.rst +++ b/docs/management_commands.rst @@ -25,10 +25,10 @@ This command moves a selection of pages from one section of the tree to another. Options: - **from** - This is the **id** of the page to move pages from. All descendants of this page will be moved to the destination. After the operation is complete, this page will have no children. + This is the **id** of the page to move pages from. All descendants of this page will be moved to the destination. After the operation is complete, this page will have no children. - **to** - This is the **id** of the page to move pages to. + This is the **id** of the page to move pages to. update_index ------------ diff --git a/docs/settings.rst b/docs/settings.rst index 018af5d0154..66fc2de9884 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -3,7 +3,7 @@ Configuring Django for Wagtail ============================== -To install Wagtail completely from scratch, create a new Django project and an app within that project. For instructions on these tasks, see `Writing your first Django app`_. Your project directory will look like the following:: +To install Wagtail completely from scratch, create a new Django project and an app within that project. For instructions on these tasks, see `Writing your first Django app `_. Your project directory will look like the following:: myproject/ myproject/ @@ -19,13 +19,7 @@ To install Wagtail completely from scratch, create a new Django project and an a views.py manage.py -From your app directory, you can safely remove ``admin.py`` and ``views.py``, since Wagtail will provide this functionality for your models. Configuring Django to load Wagtail involves adding modules and variables to ``settings.py`` and urlconfs to ``urls.py``. For a more complete view of what's defined in these files, see `Django Settings`_ and `Django URL Dispatcher`_. - -.. _Writing your first Django app: https://docs.djangoproject.com/en/dev/intro/tutorial01/ - -.. _Django Settings: https://docs.djangoproject.com/en/dev/topics/settings/ - -.. _Django URL Dispatcher: https://docs.djangoproject.com/en/dev/topics/http/urls/ +From your app directory, you can safely remove ``admin.py`` and ``views.py``, since Wagtail will provide this functionality for your models. Configuring Django to load Wagtail involves adding modules and variables to ``settings.py`` and urlconfs to ``urls.py``. For a more complete view of what's defined in these files, see `Django Settings `__ and `Django URL Dispatcher `_. What follows is a settings reference which skips many boilerplate Django settings. If you just want to get your Wagtail install up quickly without fussing with settings at the moment, see :ref:`complete_example_config`. @@ -266,9 +260,7 @@ Other Django Settings Used by Wagtail TEMPLATE_CONTEXT_PROCESSORS USE_I18N -For information on what these settings do, see `Django Settings`_. - -.. _Django Settings: https://docs.djangoproject.com/en/dev/ref/settings/ +For information on what these settings do, see `Django Settings `__. Search Signal Handlers diff --git a/docs/sitemap_generation.rst b/docs/sitemap_generation.rst index 9c6d50e48b2..203a423fb60 100644 --- a/docs/sitemap_generation.rst +++ b/docs/sitemap_generation.rst @@ -1,3 +1,5 @@ +.. _sitemap_generation: + Sitemap generation ================== diff --git a/docs/wagtail_search.rst b/docs/wagtail_search.rst index 6a77b06f3c0..4c0a1ac74c9 100644 --- a/docs/wagtail_search.rst +++ b/docs/wagtail_search.rst @@ -1,5 +1,5 @@ -.. _search: +.. _wagtail_search: Search ======