New Help System

[carsten.klein@…]

I noticed the effort currently under way to externalize the help pages and guides from the wiki into a separate, non versioned storage. While I think that this would be rather nice, I would like to comment on the proposed solution that can be found under TracDev/Proposals/NewHelp.

The extension point interface is quite ok, but I would like it to be so that the user must not reimplement the wheel twice in respect to the get_help_page_content method:

So I would rather like to the see interface similar to the below

class IHelpProvider(Interface):
    """Extension point interface for components that provide pages
    to the Help system and its related features.
    """

    def get_help_pages_locator():
        """Either returns the resource location and the mimetype of 
        the help pages provided by this, or a generator function 
        that will be called for accessing the page content, which 
        in turn will provide both the content and the mimetype 
        associated with that content."""

    def get_help_pages(locale_id):
        """Returns help pages provided by the plugin as a generator
        of tuples of the form: `(section, title, page_id)` """

That way, the most common implementation, i.e. help pages located in the filesystem (or an egg-archive thereof), can directly be implemented into trac, no need for the user to reimplement it for every extension out there.

The more special cases then would return a callable locator that then in turn would resolve and locate the content and the mimetype of the content. In fact the locator function will behave like the already defined get_help_page_content(page_id, locale_id) method.

Of course, in the future, trac could be adjusted so that it would support multiple different resource locations instead of just the relative-to-the-component-folder location. For example external databases, or, again, pages in the wiki.

This could also make room for yet another extension point, e.g. IHelpLocator or something similar.

[osimons]

Hi Carsten, and thanks for your interest in the branch. It is somewhat behind schedule…

Anyway, the proposal is an open proposal, with lots of room for adding comments and feedback and suggestions directly on the wiki page. Add a section with your comments, or inline questions and suggestions as you see fit. Tracking wiki feedback through tickets will not be manageable over time.

The only real restriction for editing proposals is that you should not directly change the details of it or change the APIs and/or decisions made so far by Trac developers. Other than that, feel free to clarify, suggest or approve/disapprove ideas. Your feedback will be merged into some future revised proposal.