darcsforge.deepdish – Deep Linker

Platforms: Django

Deepdish is the interface, the glue application, between several Darcsforge applications. It provides several useful extensions to the reStructuredText markup for doing interesting cross-references between Darcsforge entities such as between Patches and corresponding Issues. If placed in your Django settings under INSTALLED_APPS Deepdish will add cross-reference models and will add cross-references into these models for added backlinking.

Deepdish can be compared to Trac’s Wiki markup. Deepdish simply provides modules for an existing markup environment, however, and does not directly interface with any other application unless installed, and assuming the other application uses an appropriate DARCSFORGE_CONTENT_FORMATTER.

Contents

• darcsforge.deepdish – Deep Linker
  • reStructuredText Markup
    • Issue Reference
    • Milestone Reference
    • Patch Reference
  • Content Formatter
    • Deeplinking

reStructuredText Markup

class formatters.ReStructuredText

The ReStructuredText content formatter is the primary Darcsforge content formatter.

The following are the cross-reference patterns that Deepdish enables in the presence of installed Darcsforge applications when using reStructuredText:

Issue Reference

Issues are referenced via the reStructuredText inline markup:

:issue:`YYYY-Mon-DD issue-slug`

The date is the original posted date.

Milestone Reference

Milestones are referenced via the reStructuredText inline markup:

:milestone:`milestone-slug`

Patch Reference

Patches are referenced via the reStructuredText inline markup:

:patch:`YYYY-Mon-DD patch-slug`

The date is the creation date on the patch.

Content Formatter

A Deepdish content formatter has a relatively simple calling pattern, but is used to render a collection of different Darcsforge content:

from django.conf import settings
cf = settings.DARCSFORGE_CONTENT_FORMATTER()
formatted_text = cf.format(text)

Deeplinking

A ContentFormatter format can build an immediate unidirectional link. Additionally, Deepdish provides a handful of many-to-many tables and the content formatter can be asked with appropriate models to save cross-references to the appropriate many-to-many table:

someModel.formatted_text = cf.format(text)
cf.deeplink(someModel)

Note that a content formatter is only expected to keep track of the deep links involved in the most recent formatted text.