Make built-in documentation independent from wiki

[flo@…]

I noticed that there are various links to the built-in documentation pages in the wiki. We use the wiki for internal documentation and development matters and therefore anonymous users don't have rights to access it. So it would be nice if the online documentation pages would be independant from the wiki, because anonymous users can't view them if they have no right to access the wiki and it is annoying if you have those links to is everywhere, which lead you (as an anonymous user) to pages which say "Access denied". A quick workaround would be to only display the links if you have rights to access the wiki.

Best regards

Florian Lahr

[Felix Collins]

I propose that the Trac guide and associated "default" wiki pages are converted at release time (of Trac) to static HTML that is shipped with a trac install and served out alongside the other static Trac content (ie the templates). The conversion should be an automatic part of the build process and the converter should be built into the Trac code itself, perhaps as part of trac-admin. A manual conversion would of course also be possible from the web interface too with a ui allowing the selection of a subset of pages to convert.

A side effect of this of course would be to add a feature to Trac to allow HTML documentation generation from the wiki! What a great feature.

[simon-code@…]

For me, the built-in Help problem is actually two issues:

1. The wiki pages that "clutter" project documentation (as descibed above)
2. The TracGuide help link in metanavigation that is hard-coded into the WikiModule (see /trunk/trac/wiki/web_ui.py@2976#L46).

It should be possible to remove/disable this help link without changing Trac source.

Proper handling of Help should be a priority for planned multi-project support.

[trac@…]

I like the above comments, but I have another (maybe easier to implement) idea. Create a configuration parameter or inter-trac parameter such that when the Wiki web_ui is disabled or you don't want to have Trac documentation in the project itself, that help references are replaced with an external URL. By external URL, I mean the URL of a different Trac project (sort of an implied inter-Trac link).

Of course, using this capability to link to trac.edgewall.org would be a poor use, but you could set up a separate/dummy documentation project with only the Trac documentation in read-only mode (and turn off everything except the wiki in that project).

[mgood]

Replying to trac@digidescorp.com:

I like the above comments, but I have another (maybe easier to implement) idea. Create a configuration parameter or inter-trac parameter such that when the Wiki web_ui is disabled or you don't want to have Trac documentation in the project itself, that help references are replaced with an external URL. By external URL, I mean the URL of a different Trac project (sort of an implied inter-Trac link).

The problem with linking to another project for the docs is that every time someone clicks one of the help links they'll now be browsing another project, which would lead to a lot of confusion.

[trac@…]

Replying to mgood:

The problem with linking to another project for the docs is that every time someone clicks one of the help links they'll now be browsing another project, which would lead to a lot of confusion.

Yes, that's why I thought it should be configured as read-only and wiki-only.

Looks like I may want something like this soon. Upper management here feels that having both the corporate wiki and Trac's wiki is too confusing, so we're probably going to turn off Trac's wiki. The problem is, if we actually turn it off, then we will end up with about 90 Trac environments without help pages.

[cboos]

[OT] Reply to trac@digidescorp.com:

... we will end up with about 90 Trac environments ...

Wow, that must be a world record ;)

[mgood]

Replying to trac@digidescorp.com:

Looks like I may want something like this soon. Upper management here feels that having both the corporate wiki and Trac's wiki is too confusing, so we're probably going to turn off Trac's wiki. The problem is, if we actually turn it off, then we will end up with about 90 Trac environments without help pages.

Well, I wouldn't think you'd need to completely disable the Trac Wiki. Just turn off editing and make something else the default page. That way it's still on for browsing the Trac docs, but you don't need to use it for your own documentation.

[trac@…]

Yes, I suppose disabling editing would be fine. I'll have to change the permissions scheme, though (right now, everyone's an administrator, just for simplicity).

[cboos]

href.wiki links in the templates could be replace with href.help ones, and that specific handler could belong to a "mini" wiki module, which only gives view access to the help related pages. Therefore, the TracGuide would remain available even in environments having the wiki module disabled or for users not having the WIKI_VIEW permission.

[simon-code@…]

Replying to cboos:

href.wiki links in the templates could be replace with href.help ones, and that specific handler could belong to a "mini" wiki module, which only gives view access to the help related pages. Therefore, the TracGuide would remain available even in environments having the wiki module disabled or for users not having the WIKI_VIEW permission.

This is sort of what I have done for my hosting setup. However, I have taken it a bit further with my [help:...] links in that I source in pages for Help both from a local and remote project. The advantage is that each individual project does not need to be cluttered with various Trac and other Help pages in all shapes and sizes.

I needed to resort to various trickery to get this to work well. However, on my mod_python setup it is snappy and performing well, and all Help navigation stays local within the project (Help module) regardless of where the page originally came from.

I use some custom options for the module in my global trac.ini - kind of like:

[help]
help_pages_project = /path/to/other/project/or/empty/if/only/local
global_help_pages = HelpUser, HelpAdmin, HowTo, FAQ
local_help_pages = HelpProject

However, since I wrote this 1,5 years ago I have learned much more about Trac, and would certainly do it slightly different now. My idea now would be to have a Help module that is extensible through an interface - a HelpPageProvider kind of thing. Using your idea the local wiki would then be one (default) provider to a general Help module providing main matching, navigation and so on (kind of like Admin).

A provider would need to do a number of things:

• Provide page list, headings and extra information for building menus and navigation
• Provide match logic for links
• Do actual render and return output

I render remote help pages in the remote project (a trade-off on issues that arise as no ideal way to do this today) such as all links rendered as missing locally - the cost is that I have to "massage" the content a little by redoing any URL pointing to a Help page.

However, a Help module might remedy that - and certainly if I had used [help:...] links instead of wiki links in my remote wiki. Then it would just be a matter of checking the help index to verify if it exists or not, and even remote pages could be rendered locally.

Using this extensible idea, one could also imagine a Help provider that fetches pages from t.e.o and caches locally in a separate table - weekly updates, Admin interface or whatever. Anything would be possible using the excellent plugin architecture you have.

I'll gladly help if I can if/when the time comes to look at these issues.

I'll attach a screenshot of my Help module next - mostly to illustrate real-life usage, and hopefully provide some inspiration :-)

[simon-code@…]

Traceback trying to upload screenshot? Anything wrong at t.e.o.?

Forgot to mention one more problem I have had: Lots of hardcoded links in templates to help pages that I have had to replace with my own. This should also be a bit more generalised as it assumes local wiki page with the same name exists. Link to a help module with matching would also fix that in code.

[cboos]

Replying to simon-code@bvnetwork.no:

Traceback trying to upload screenshot? Anything wrong at t.e.o.?

Yes, #4087, please send the picture to me and I'll attach it.

About the help module, the idea of using help: TracLinks within help pages certainly makes sense. The ability to fetch pages from "somewhere else" is also interesting, but I think this should probably be limited to "importing" them from a specific project, in case of multiple project support (see #130 and Global or Shared Resources?).

[cboos]

The screenshot simon was talking about, uploaded by me because of #4087...

[cboos]

See also #3386 for an alternative idea regarding the help links.

[anonymous]

Replying to cboos:

See also #3386 for an alternative idea regarding the help links.

That works. Could it be used to introduce project-specific namespaces to the wiki as well (as part of multi-project support?)

[cboos]

Also, we need to figure out what to do with the default set of wiki pages at install time (#1626):

• copy them anyway, even if they're not used
• [inherit] wiki_default_dir = ...?

[osimons]

This is the essence of TracDev/Proposals/NewHelp, so I'll grab ownership of this one.