Skip to content
Tag items in Sphinx documentation and make lists of tags
Python
Latest commit dfda8b2 Jul 5, 2014 @spinus commit of death
Failed to load latest commit information.
sphinxcontrib tag directive: match tags like .*? instead of .* Mar 19, 2012
.gitignore init Mar 18, 2012
MANIFEST.in init Mar 18, 2012
README commit of death Jul 5, 2014
setup.py init Mar 18, 2012

README

Sphinx "taglist" extension.

PROJECT IS NOT MAINTAINED, IT IS DEAD.

TagList
=======

.. warning::

    THE PROJECT IS DEPRECATED (NOT MAINTAINED ANYMORE)


Taglist is an extension to Sphinx documentation system.

.. note:: 

    The project it is a totally copy of sphinxcontrib-requirements with
    some modifications

Installation
------------

Instalation through pip: ::

    pip install sphinxcontrib-taglist

or through github: ::

    git clone https://github.com/spinus/sphinxcontrib-taglist
    cd sphinxcontrib-taglist
    python setup.py install

Next, you have to add extension to 'conf.py' in your sphinx project. ::

    extensions = [
              ...,
              'sphinxcontrib.taglist',  
              ...]


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

When using `tags` with this extension you may want give each tag other color.
You can do that in 'conf.py' by adding: ::

    taglist_tags = {
        'tag1': {'background-color': 'green'}
    }


Directives
----------

tag:
    tag directive add a 'piece' of information, and you can tag it.

    You can use it like: ::

        .. tag:: Some tagged information
            :tag: tag1 tag2 tag3 

    or: ::

        .. tag:: [tag1 tag2 tag3] Some tagged information

    .. warning:: 

        Second method is used only if first method is not.

    .. warning:: 

        I am not sure this syntax, it may change. 
        If you have anny suggestions please let me know.

taglist:
    taglist is a directive which `catch` tags and do a list.

    Firstly it prints 'Tags: ...' with information which tags it displays, and 
    than it shows the list.

    You can use it like: ::
        
        .. taglist::
            :tags: tag1 tag3

How it works?
-------------

The codebase is derived from `sphinxcontrib-requirements` so it works in similar
way.

During document reading `tag` directives create `tag_node`s.
`taglist` create `taglist` nodes.

During resolving `taglist` nodes are changed to a piece of text `Tags:` with
tags items which will be displayed on that list.
Next it prints all tagged items.


CSS
~~~

taglist.css:
    It contains base class for tag - taglist_tag

    .. warning:: 

        It probably will be changed and put in `taglist_tags.css`.
        (And it will be configurable from `conf.py`)

Additionally, it creates the file `taglist_tags.css` during processing (with
css for each tag you defined in `conf.py`; `taglist_tags` maps all tag keys to
css keys) and write it to build directory to static files.


Questions and suggestions
-------------------------

If you have some suggstions, patches, problems - please write an email.

Something went wrong with that request. Please try again.