sphinxcontrib-spelling / traclinks /

Filename Size Date modified Message
..
sphinxcontrib
1.1 KB
49 B
2.1 KB
81 B
1.1 KB
.. -*- restructuredtext -*-

==================================
README for sphinxcontrib.traclinks
==================================

:author: Kevin Horn <kevin.horn@gmail.com>

.. module:: sphinxcontrib.traclinks
   :synopsis: Create TracLinks_ to a Trac instance from a Sphinx project.


This Sphinx extension adds a docutils role to create links to a Trac 
instance.

Licensing
---------
This code is released under an MIT License.  
See the LICENSE file for full text.

Requirements
------------
The target trac instance *must* support dispatching of InterTrac_ links.

For example, it must know what to do with a link like this::
    
    http://trac.edgewall.org/intertrac/ticket:1234


Installing from sphinx-contrib checkout
---------------------------------------

Clone the sphinx-contrib repository::

  $ hg clone https://bitbucket.org/birkenfeld/sphinx-contrib/

Change into the traclinks directory::

  $ cd sphinx-contrib/traclinks
  
Install the module::

  $ python setup.py install
  

Enabling the extension in Sphinx_
---------------------------------

To enable the use of this extension in your Sphinx project, you will need 
to add it to the list of extensions in the ``conf.py`` file in your Sphinx 
project.

For example::

    extensions = ['sphinxcontrib.traclinks']


Configuration
-------------

You will need to set the following config value in your Sphinx project's 
``conf.py`` file::

``traclinks_base_url`` <string>:
    The base url of the Trac instance you want to create links to.
    
Usage
-----

In your restructuredText markup, you can create links to various Trac 
entities using markup of the following format::

    :trac:`trac-links-text`
    
where ``trac-links-text`` is valid TracLinks_ markup.

For example, to link to a Trac ticket::

    trac:`#1234`
    
Or to link to a Trac wiki page::

    trac:`wiki:TracWiki`

.. Links:
.. _Sphinx: http://sphinx.pocoo.org/
.. _TracLinks: http://trac.edgewall.org/wiki/TracLinks
.. _InterTrac: http://trac.edgewall.org/wiki/InterTrac
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.