Battery on laptop is dying, so I will keep this quick. On May 21, 2008, at 6:43 AM, osimons wrote: > > 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.
If we can come up with a good solution for localizing ReST documentation, and someone want to contribute the translations, I see no reason to not translate these too. I agree it need not be a priority though. Docstrings will probably always be in English. > 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. I will check with the experts on this one. > > 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: > > Àre there other alternatives? As I said before, for the shipped documentation, we will render down to plain HTML with sphinx-build, and include _only_ that HTML in egg file. The ReST docs are not needed from that point forward (as far as the user cares). > > > 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? Indeed, the current API looks like it does all we need. > > > 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? Yes, just not sure how best to do that. > > > 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)? Yes, this was agreed on already AFAIK. All docs, docstrings, etc will be ReST. > > > 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. Will write more cogent updates next week. --Noah --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
