New Help System
|Reported by:||Owned by:|
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.