Metadata-Version: 1.0
Name: TracSphinx
Version: 0.2.1
Summary: Sphinx plugin for Trac 0.11
Home-page: http://bitbucket.org/florent/sphinx-plugin
Author: Florent PIGOUT
Author-email: florent.pigout@gmail.com
License: BSD
Description: Sphinx plugin 0.1
        =================
        
        First draft for sphinx like easy to use plugin. It implements basic tasks to
        manage Sphinx documentation in Trac.
        
        1. Plugin install
        -----------------
        
        Download the plugin sources, unzip the archive and type the easy_install command
        from the plugin folder::
        
            $ easy_install setup.py install
        
        Restart the Trac project(s). As administator we can now activate the plugin.
        
        By default the documentation source folder is './docs/source' of the project
        repository. But in most of cases we will override this path in the *[sphinx]*
        section of the project 'trac.ini' file::
        
            [sphinx]
            source_dir = /<the_doc_source_path>
        
        This source folder is used by the project to build the sphinx documentation
        using the *web* builder of Sphinx. If the documentation can not be generated
        from Trac we can specify the generated documentation path with the following
        option::
        
            [sphinx]
            doc_dir = /<the_doc_dir_path>
        
        We also can set the navbar title with the following option::
        
            [sphinx]
            navbar_title = My documentation
        
        2. Documentation update
        -----------------------
        
        Simple params into the project url to update the documentation from the source
        folder of the project to the Trac project folder './sphinx-docs'. Just type the
        following url for update::
        
            http://<trac_url>/<project_url>?action=refresh
        
        In some cases the documentation can not be generated like in the identified
        following case:
        
            **automodule** *can not import part of the project*
        
            When we use the automodule, autoclass.. directives some projects can not
            import must requirements or config. Then Sphinx will not generate the
            project documentation and return the following error::
        
                list out of range
        
            Projects like TurboGears application are concerned. We are currently
            working on this issue and hope to purpose a solution soon.
        
        3. Documentation navigation
        ---------------------------
        
        In the right side bar of the sphinx doc in Trac we will find the three following
        functions:
        
            - Table of content
        
        Menu of the content of the current displayed page.
        
            - Relative links
        
        Include the index and module project link, and the previous/next link(s).
        
            - Search
        
        Simple sphinx like search function. No javascript here we perform the search on
        the server side.
        
        4. Url API overview
        -------------------
        
        The plugin manage the followings urls and parameters. By default the index page
        of the project documentation will be displayed.
        
            - **/<project>/sphinx**
                default index page
        
            - **/<project>/sphinx?action=view&item=<page_name>**
                *action=view* action to display a specific page of the documentation
                *item=page_name* name of the page do display
                *search_words=<some+words>* words of the current search (highlighted in the page)
        
            - **/<project>/sphinx?action=index&item=genindex**
                *action=index* display the project documentation index
                *item=genindex* display the project documentation index
        
            - **/<project>/sphinx?action=modules&item=modindex**
                *action=index* display the project modules index
                *item=genindex* display the project modules index
        
        5. Next updates
        ---------------
        
        This plugin version implements sphinx basic functionalities.
        
        Please do not hesitate to send emails or patches if you have further needs or
        if the plugin does not manage your sphinx documentation the way we want.
Keywords: trac plugin sphinx
Platform: UNKNOWN
