On May 20, 1:02 pm, Jeroen Ruigrok van der Werven <[EMAIL PROTECTED] nomine.org> wrote: > -On [20080520 03:02], Noah Kantrowitz ([EMAIL PROTECTED]) wrote: > > So trunk/doc will move to the newhelp branch? > Just need to know before I start editing the files. >
Yes, it will. As Noah is on the road atm, we just need to decide on how to move/remove. Ideally I would see that instead of adding them as new files, we moved them from wiki/default-pages whereever possible to preserve the history they actually represent. That likely means just deleting them in trunk, merging that change to newhelp, and then start creating the new structure and copy in the already converted text. However, there are some other related issues, and I've written a few words on this below... :-) Basic structure --------------- As more or less agreed above, we make 4 main guides: - Install Guide - Developer Guide/Reference - Admin Guide - User Guide Install and Developer guides ---------------------------- This should be Sphinx only, and no real point in making this information available inside Trac for normal use. I don't know Sphinx very well yet, but I suppose this means that they should only be available at the Trac site. And, as Noah mentioned we then build like nightly version for current dev (trunk) and whatever main stable branches we have in the future based on this. The guides are available as browseable HTML and PDF downloads or something as commonly done in projects. And, as noted above, we should make some effort to make a nicer template that suits us and used for all the Sphinx-generated guides... These guides are English only as I see it. User and Admin guides --------------------- These are more complicated. They can also surely be available as Sphinx guides in various formats as above, but all content in these two guides must also be available inside Trac as they deal with normal usage - users need to reference it online, we need to link to this content and reference it in various situations. They need to be split into mini-guides with a general information (for all installations), and sections/chapters related to each component. The content should be available in a general trac/guide directory, and for each major component its pages should be in a directory like trac/ versioncontrol/guide. For Sphinx, this means that the build script will need to pull in files from various locations. No doubt easily doable for someone that knows how. For Trac, it means we use the newhelp API idea and make a general Help page provider + providers for each of the components. Disable the versioncontrol component, and these Help pages also disappear from online help. Again, nothing complicated about that as it currently stands in the newhelp branch. The content pulled in for rendering inside Trac obviously needs to be renderable. Sphinx-customized rst files are currently not as they throw all kinds of errors when Sphinx is not installed. I think we all agree that Sphinx should not be a requirement for a vanilla installation, so we need to figure something out here. The current newhelp is format agnostic as long as it know the mimwtype and has a renderer for it, so I supose the alternatives are: a) Have Sphinx generate the input that we use inside Trac. This can be plain HTML output, or it can possibly be 'stipped down' rst so that we render it in Trac as regular rst. b) Make a Trac custom mimeview renderer that can read the Sphinx rst files, stip unneeded directives and render them directly like any other file. Perhaps just a 'silently ignore errors' setting in rst renderer is enough? c) Use the current wiki markup for these guides (as today), and make a Sphinx supported rendering directive that can insert Trac-generated input into the pages. The Sphinx guide can then just be stubs that provide the scaffolding and pointers to what main content to provide inside each main file. Àre there other alternatives? Decisions to be made -------------------- 1) Pluggability with regards to main docs. Currently the online help is pluggable, so that something like a blog plugin can provide additional pages available in the online guide. I see no point in directly extending this to the Sphinx documentation - newhelp should provide simple mechanisms for providing online help, but if plugin developers want to make a shiny PDF from Sphinx (or other tools) they do it on their own. Agree? 2) Localization in newhelp is supported, and currently uses the same pluggable mechanisms as a given plugin respons to one or more locales (or as a no-locale fallback). The Trac project only supplies default English guides, and leave it to plugins (language packs) to provide localized versions. Now, this is different from the pot and message strings strategy where we actually handle it. The subject of the apis and non-existent pluggability of message strings is related (although likely the subject of another thread), and we need to decide on the direction as it effects how we now transform the branch to new-help- and-docs (code + storage structure). Do we want/expect the Trac project to include the localiztions of documentation? 3) What format do we use for content? Adopting Sphinx for all guides, it would make by far the most sense to move all documentation to rst. There are disagreements here, and personally I've been in the camp that would prefer that we use and improve the current Trac tools and markup for documentation. However, I'll go with the flow and respect the decision of what seems to be the majority of votes. Is the decision then made to convert all docs to restructured text (rst)? Other issues ------------ The TracDev/Proposals/NewHelp wiki page has some other open issues that are well kept in mind when finalizing the structure. For instance making the online guides searchable in various formats and languages. The proposal should be updated to cover all related issues once we have a shared sense of direction on this. :::simon https://www.coderesort.com --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Trac Development" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/trac-dev?hl=en -~----------~----~----~----~------~----~------~--~---
