sphinxcontrib_section_autoref

index.txt

===================
Example of autoref
===================

Section 1
==========

You can write reference to section title without any definitions:

  :ref:`Section 1`
  :ref:`Section 2`
  :ref:`index/Section 1`


Section 2
==========

Hello world

sphinxcontrib_section_autoref.py

# -*- coding: utf-8 -*-
"""
    sphinxcontrib_section_autoref
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Add link-target labels to every sections automatically.
    You can make reference :ref:`section-name` without label defintions.

    And more, labels which are similar to wiki-names (cf. index/secition-name) are
    added in same time.

    :copyright: Copyright 2012 by Takeshi Komiya.
    :license: BSDL.
"""
import os.path
from docutils import nodes, transforms
from docutils.nodes import fully_normalize_name as normalize_name


class AutoReferenceTransform(transforms.Transform):
    application = None
    default_priority = 500

    def apply(self):
        filename = os.path.relpath(self.document['source'], self.application.env.srcdir)
        docname = os.path.splitext(filename)[0]
        for target in self.document.traverse(nodes.section):
            # append global link-target including docname (cf. index/section-name)
            name = docname + '/' + normalize_name(target[0][0].astext())
            target['names'].insert(0, name)

            self.document.note_explicit_target(target)


def setup(app):
    AutoReferenceTransform.application = app
    app.add_transform(AutoReferenceTransform)