Sphinx?
Noah Kantrowitz
system (http://sphinx.pocoo.org/)? It seems to provide a number of nice
support functions beyond simply putting each doc in a file and running
rst2html or something. The pickle builder would be a good starting place
for the integration with osimmion's newhelp interface (I think). This
would mean Sphinx and Pygments would be required for building the
documentation (and therefore for building release media), but neither
would be runtime dependencies. Thoughts?
--Noah
Alec Thomas
I've been converting the documentation for my own applications to
Sphinx, and it's been a very pleasant experience. As a bonus, I think
it would also save us a lot of work.
Alec
--
Evolution: Taking care of those too stupid to take care of themselves.
osimons
On May 14, 2:29 pm, "Alec Thomas" <a...@swapoff.org> wrote:
> 2008/5/14 Noah Kantrowitz <kan...@rpi.edu>:
>
> > What would people think about basing our new docs around the Sphinx system
> > something. The pickle builder would be a good starting place for the
> > integration with osimmion's newhelp interface (I think). This would mean
> > Sphinx and Pygments would be required for building the documentation (and
> > therefore for building release media), but neither would be runtime
> > dependencies. Thoughts?
>
> I've been converting the documentation for my own applications to
> Sphinx, and it's been a very pleasant experience. As a bonus, I think
> it would also save us a lot of work.
>
ready, and I agree that it does look promising. I say that having just
browsed the front page and some minimal docs, and have no real clue or
idea as to how to do this yet. I would need to actually install and
play with it, which I just have not found time to do yet. Nor has it
been a high priority issue for me to make 'ring-bound' documentation -
my main motivation was moving the pages out of the wikis of each
project, and rendering them using available Trac mimeviewers depending
on format - which is all Trac wiki for the time being.
With the plugin architecture for providing help pages + being format
agnostic, 'newhelp' tries to make it effortless for others to provide
documentation as an ever-increasing part of Trac is provided by
plugins. And, add to this the i18n issues of providing some/all the
pages localized...
Sphinx looks interesting and I will look into it at some stage, but
I'm mostly wondering about what problem to actually apply it to? Would
it be to run extractions to create development and reference guides -
ie. different from the typical user guides that a continuation of the
wiki/newhelp provides? Our to collect the usage documentation we have
+ add lots of documentation we don't have today, and make some sort of
official trac-book to accompany major and minor releases?
Increasing the quantity and quality of official published
documentation on the project is a massive undertaking - regardless of
how it is done and with what tools. I'd rather we started in the other
end by agreeing on what documentation we (and plugin providers) should
provide to the community of users and developers. It then becomes
easier to evaluate and discuss individual tools for the job.
:::simon
https://www.coderesort.com
Noah Kantrowitz
This would accompany moving from the wiki to ReST-formatted files in
Subversion. Sphinx To start with I don't forsee providing any more than
the current TracGuide pages do, but a real developer tutorial and guide
would be much appreciated I think. We would use sphinx to generate the
files served by newhelp (for the trac section of it at least, plugins
can use whatever they want as you said).
I've been fooling around with all this for the morning, and I think it
will be a very good match for us. I am working on a PoC conversion of
some of the install docs to use as an example.
--Noah
Noah Kantrowitz
>
> I've been fooling around with all this for the morning, and I think it
> will be a very good match for us. I am working on a PoC conversion of
> some of the install docs to use as an example.
Okay, I did some initial rewrites of the TracInstall, TracCgi,
TracFastCgi, and TracModPython pages into ReST+Sphinx.
https://coderanger.net/~coderanger/tracdoc/install/index.html
You can use the "view source" link on each page to see the raw markup.
There is also a PDF generated from the same sources up at
https://coderanger.net/~coderanger/tracdoc/Trac.pdf
Thoughts?
--Noah
Christian Boos
Sphinx is indeed nice, but I'd rather see it's usage at the level of
generating the API docs rather than for the TracGuide.
I've started some months ago to clean-up the API docstrings in order to
produce a reference manual using epydoc, but I stopped that effort as I
found no good solution for the docstrings that should stay in Wiki
markup (like the config options doc for TracIni and the wiki macro
documentation). I had a look at Sphinx, and I have the impression it
might be easier to extend it so that it could handle both styles.
> Increasing the quantity and quality of official published
> documentation on the project is a massive undertaking - regardless of
> how it is done and with what tools. I'd rather we started in the other
> end by agreeing on what documentation we (and plugin providers) should
> provide to the community of users and developers. It then becomes
> easier to evaluate and discuss individual tools for the job.
>
I agree, let's first discuss what is the documentation we want to
provide, then which tools.
I see three targeted audiences:
1. users, which have to figure out what they can do in Trac, and how to
do it
2. administrators, which have to know how to manage and configure a
Trac installation
3. developers, which in addition have to know the inside outs of Trac
and have an API reference
For 3. and most notably for generating the API reference, it makes no
doubt we need a specialized tool, and I agree that Sphinx seems even
better than epydoc in this respect (but a more detailed comparison in
what we'd loose/gain should eventually be made).
Nevertheless it's quite early in the game, as we don't have anything
yet, so it seems to be the appropriate time to choose one or the other.
I'm a little biaised against epydoc, because as I said above, I failed
to see how to extend it so that it could handle the wiki markup parts.
Now, for 1. and 2., the first remark is that we until recently didn't
make a difference between those two audiences, and the structure of the
TracGuide somewhat reflects that. For 0.11, I've made two main sections
in the TracGuide page, but that's not really enough. What would be
actually needed is two guides.
The Trac User Guide could even be much more "user" oriented, being more
visual (snapshots). It should show how to use Trac and for that there
should be two levels:
- introductory level, suitable for a 2 minutes reading
- reference level, like the complete WikiFormatting guide
The Trac Admin Guide should also eventually have those two levels, like
a quick install and setup guide (which would eventually be displayed
right after the installation) and also a more in-depth reference guide
for all the various deployment and troubleshooting situations. Speaking
of troubleshooting, a cleaned-up FAQ would be of a tremendous help ...
for the help system.
Now, where would that documentation (for 1. & 2.) come from? We don't
start from nothing here, we already have a TracGuide which has evolved
over the years, since Trac's inception.
During the +2 years of 0.11 development (and even before since the 0.9
and 0.10 days), I've heard a lot of complaints about our poor
documentation or lack thereof, but I've seen little activity in this
area, so I find it hard to believe that a change of documentation format
or tools would make a difference and that would suddenly motivate us to
write more or better docs. Quite to the contrary, I find it critical
that we continue to offer the possibility for our users and contributors
to freely edit the TracGuide related pages on t.e.o, as those
contributions are essential in keeping the documentation alive. Those
contributions must be easy to integrate back in the official
documentation, without requiring a format translation. So for me this is
a strong argument in favor of keeping the user and admin documentation
in wiki markup.
The second argument is that if the TracTeam (tm) doesn't use its own
wiki formatting and rendering chain, why should others trust it for
writing their own documentation? If there are problems with that
formatting or the rendering chain which makes it a sub-optimal solution
compared to other tools (in the same category), then our "job" would be
to fix it. Otherwise by the same kind of argument we could have switched
to say, Roundup for our bug tracking needs, if some had considered it
would have been better than Trac in this respect.
Well, at least some people have faith in what Trac can do:
http://www.packtpub.com/article/software-documentation-with-trac
And I don't see why we should stop improving Trac abilities in this domain.
Here are some of the relevant work items:
- the WikiEngine refactoring which will make it possible to generate
structured output (e.g. Genshi events or docutils nodes, so that we
could hijack the docutils writers for generating the static documentation)
- Section editing (#1024) so that big pages like the FAQ could be
easily edited
- Much improved table markup (the reST table markup is unbearable)
- Lots of possible minor improvements to the syntax and rendering, in
order to make writing documentation a more enjoyable experience (i.e. we
have full control over the feature set)
Bottom line:
Improving the documentation system for Trac should motivate us to make
Trac better at writing documentation, not prompt us to ditch Trac in
favor of another tool for doing that job.
-- Christian
(PS: I'll discuss the newhelp branch in another mail, as that's a
separate topic, which is format agnostic)
Noah Kantrowitz
> Bottom line:
> Improving the documentation system for Trac should motivate us to make
> Trac better at writing documentation, not prompt us to ditch Trac in
> favor of another tool for doing that job.
This was discussed in depth a while ago, but I will sum up the key
points here.
1) A wiki exists for communication, taking quick notes, and to act as a
general buffer between both developers and the community. It is _not_ a
system to write good technical documentation. We have optimized both our
wiki syntax and editing system to match these intentions IMO, so I don't
consider this a problem. Some documents which need rapid editing from
many people will remain better suited to being in the wiki, an example
being the proposals that live under TracDev. Our actual documentation is
another story. One big reason to move to ReST files in Subversion is we
gain easy branching, thus warding off the current insanity with
0.1[012]/* page names and such. It also allows us to move to a
submit-a-patch workflow as we do with code. Documentation is just as
critical as any other part of the project, and as much as I like
community involvement, it has become clear through experience that wikis
do not work for our needs. ReST has an existing and powerful
documentation toolchain that very closely matches our needs, so I think
it is a logical fit. We will indeed be "eating our own dogfood", as the
newhelp system designed for this will be exposed to projects using Trac
for their own documentation needs (with the t.e.o methodology and
toolchain serving as an example of how to use it).
Now to get back to the original topic at hand, I am happy with Sphinx
and I think we should use it for our toolchain. The TOC and index
systems are very nice and easy to use. I played around a bit with the
autodoc extension, and it works quite nicely for pulling docs in from
the source code, and makes it easy to add manual tweaks here and there.
I currently see things being broken into 4 main doc trees: guide (user
docs), admin (administration guide), install (install process), and api
or dev (developer reference and tutorials).
--Noah
Jeroen Ruigrok van der Werven
>A wiki exists for communication, taking quick notes, and to act as a
>general buffer between both developers and the community. It is _not_ a
>system to write good technical documentation.
Fully agreed in my capacity as a technical writer/programmer.
>Our actual documentation is another
>story. One big reason to move to ReST files in Subversion is we gain easy
>branching, thus warding off the current insanity with 0.1[012]/* page names
>and such. It also allows us to move to a submit-a-patch workflow as we do
>with code. Documentation is just as critical as any other part of the
>project, and as much as I like community involvement, it has become clear
>through experience that wikis do not work for our needs.
Peer review has been difficult, in my opinion, with the wiki. This lead to a
lot of problems with the structure of the documentation, making it hard to
find the appropriate things.
>I currently see things being broken into 4 main doc trees: guide (user
>docs), admin (administration guide), install (install process), and api or
>dev (developer reference and tutorials).
Agreed.
--
Jeroen Ruigrok van der Werven <asmodai(-at-)in-nomine.org> / asmodai
イェルーン ラウフロック ヴァン デル ウェルヴェン
http://www.in-nomine.org/ | http://www.rangaku.org/ | GPG: 2EAC625B
If Winter comes, can Spring be far behind..?
Emmanuel Blot
(although I found the default Python template for HTML output utterly
ugly and I hope somebody will come with a better alternative for Trac
;-))
As a side note, the output is not XHMTL strict as we produce w/ Trac,
only XHTML transitional. It seems there a very few efforts to produce
XHTML strict though.
Cheers,
Manu
rupert....@gmail.com
> Christian Boos wrote:
> > Bottom line:
> > Improving the documentation system for Trac should motivate us to make
> > Trac better at writing documentation, not prompt us to ditch Trac in
> > favor of another tool for doing that job.
>
> This was discussed in depth a while ago, but I will sum up the key
> points here.
>
> 1) A wiki exists for communication, taking quick notes, and to act as a
> 0.1[012]/* page names and such. It also allows us to move to a
> submit-a-patch workflow as we do with code. Documentation is just as
> critical as any other part of the project, and as much as I like
> community involvement, it has become clear through experience that wikis
> do not work for our needs. ReST has an existing and powerful
> documentation toolchain that very closely matches our needs, so I think
> it is a logical fit. We will indeed be "eating our own dogfood", as the
> newhelp system designed for this will be exposed to projects using Trac
> for their own documentation needs (with the t.e.o methodology and
> toolchain serving as an example of how to use it).
branch the wiki including the tickets, documents, and source code is
one of our major issues in getting more user acceptance for trac.
because first it is an idea or a ticket, then it should be documented.
and there should be a trace how things developed. so christians idea
has some appeal ... for us anyway.
moinmoin btw even tries to get a mercurial backend, see
http://code.google.com/soc/2008/moin/appinfo.html?csaid=1050E6FC80FD185E.
rupert.
Matt Good
> while i see the point you make, noah, not beeing able to freeze/tag/
> branch the wiki including the tickets, documents, and source code is
> one of our major issues in getting more user acceptance for trac.
> because first it is an idea or a ticket, then it should be documented.
> and there should be a trace how things developed. so christians idea
> has some appeal ... for us anyway.
value as a documentation tool, but that shouldn't stop Noah & others'
momentum on rewriting the documentation.
Noah's efforts with Sphinx push us in the right direction for how we
want to distribute the documentation, which is a separate issue from
how we maintain it. Distributions should include a standalone set of
documentation in HTML and/or PDF formats and be provided inside the
application within a new Help module so that they're available even
when the Wiki has been disabled.
I also hope we can agree that the current free-for-all editing of the
documentation in the t.e.o Wiki has become unsuitable for maintaining
well-written docs. Moving them into the source tree with a more
formal patch acceptance process should help that, so let's let Noah
continue his current work and start a new discussion for how to
improve Trac to the point where it's suitable for maintaining the docs
at some point in the future.
-- Matt
osimons
On May 19, 7:25 pm, Matt Good <m...@matt-good.net> wrote:
> I think it's useful to continue discussing ways to improve Trac's
> value as a documentation tool, but that shouldn't stop Noah & others'
> momentum on rewriting the documentation.
>
> Noah's efforts with Sphinx push us in the right direction for how we
> want to distribute the documentation, which is a separate issue from
> how we maintain it. Distributions should include a standalone set of
> documentation in HTML and/or PDF formats and be provided inside the
> application within a new Help module so that they're available even
> when the Wiki has been disabled.
>
> I also hope we can agree that the current free-for-all editing of the
> documentation in the t.e.o Wiki has become unsuitable for maintaining
> well-written docs. Moving them into the source tree with a more
> formal patch acceptance process should help that, so let's let Noah
> continue his current work and start a new discussion for how to
> improve Trac to the point where it's suitable for maintaining the docs
> at some point in the future.
that I think is agreed by all in earlier discussions and earlier in
the thread. As for standalone documentation, it does seem like Sphinx
is a good choice - and of course, any effort to review and improve the
content is most welcome. Reusing help pages for internal rendering and
standalone documentation is surely what we would want.
The objection I would like to raise at this stage is how this initial
proof-of-concept is committed to trunk. Having created a newhelp
branch (with proposal) and tried an approach to solving it from the
Trac side with flexibility for help page providers of any kind, I do
think Noah shortcuts a process of refinement and issue resolving that
is nowhere near finished. The new pages are committed as fresh pages
without history, they are committed to a 'doc' directory that is
outside the package that gets installed (and won't be available for
internal help), the rst markup expects Sphinx to be insalled and
produces countless errors when using plain trac rst mimeview
rendering, and issues like localization of help pages is not at all
considered.
We all agree that the docs need fixing, and a number of people are
eager to get it done. I would however prefer that this happened
outside the trunk for the time being so that we can arrive at a full
working solution for all documentation before exposing it in trunk.
:::simon
https://www.coderesort.com
Noah Kantrowitz
I spoke to people about this before starting to make sure it would
work for us. Before releasing a version we can use the pickle output
builder (or a similar subclass we develop ourselves if this should
prove insufficient) to dump the documentation to HTML fragments in a
folder structure that will be included in the egg. These would be
entirely rendered, so neither docutils not Sphinx will be required on
a normal install. This rebuild step can be run from a post-commit hook
on trac.edgewall.org to keep it always up to date. These HTML
fragments would be what your newhelp system would serve up. The two
actually complement each other very nicely IMO. I think this should do
exactly what we want, but feel free to point out if I am missing
somehthing.
--Noah
Noah Kantrowitz
Just some quick notes from a brief IRC discussion. osimons convinced
me that moving the docs into the newhelp branch would be a good idea
for now, just to touch trunk as little as possible. I will work on
getting a post-commit hook for trac.edgewall.org ready so that we can
have automagically update docs to point people at even before newhelp
is ready for use.
--Noah
Jeroen Ruigrok van der Werven
>Just some quick notes from a brief IRC discussion. osimons convinced
>me that moving the docs into the newhelp branch would be a good idea
>for now, just to touch trunk as little as possible.
So trunk/doc will move to the newhelp branch?
Just need to know before I start editing the files.
osimons
> -On [20080520 03:02], Noah Kantrowitz (kan...@rpi.edu) wrote:
>
> So trunk/doc will move to the newhelp branch?
> Just need to know before I start editing the files.
>
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
Noah Kantrowitz
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
Christian Boos
> Install and Developer guides
> ----------------------------
>
>
> 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...
>
The Genshi/epydoc related stylesheets could eventually be of some help
here, as they already deal with the docutils classes (see
http://svn.edgewall.org/repos/edgewall/tools/doc/style/).
> These guides are English only as I see it.
>
> User and Admin guides
> ---------------------
>
> ...
>
> 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.
>
It should be plain HTML, even a stripped down .rst would still require
docutils, which is also an optional dependency.
> 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?
>
Same as above, it would require docutils. But that would be very useful
on t.e.o itself, nevertheless.
> 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.
>
That might eventually be possible one day once we can generate docutils
compatible output from wiki markup, but not for now (see also point 3.
below).
> Àre there other alternatives?
>
Noah already answered that one: Sphinx provides some support to
"compile" the rendered output in pickled files (PickleHTMLBuilder), so
we could handle those pickled files just like the .mo files for
translations.
See http://sphinx.pocoo.org/builders.html#pickle-builder-details
> 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?
>
Yes.
(...)
> 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)?
>
Well, I can understand the need for .rst if we want to produce static
documentation, as there's no good alternative yet. However I fail to see
how the reStructuredText markup in itself is any superior to the Trac
wiki markup (in my eyes, it's not), so I think the main differentiator
is in the toolchain and the fact that sphinx and docutils bring a lot of
added value. Like I said in a previous mail, I think it will eventually
be possible to bridge this gap by having Trac generate .rst markup from
wiki markup, in the spirit of your point c. above. Of course, this is
not yet possible, and so it seems easier to convert all the
documentation we have to .rst. One of the positive outcome that could
eventually happen during such a conversion is that this could be the
occasion to clean-up the existing docs or write new docs (like in
trunk/doc/install).
But I think only time will tell if all the documentation will be
converted and if the documentation can be better maintained in that format.
-- Christian
Christian Boos
> Battery on laptop is dying, so I will keep this quick.
> On May 21, 2008, at 6:43 AM, osimons wrote:
>
>> 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.
>
I don't remember having said I agreed, but at the same time I'm getting
old...
Well Noah, do whatever you seem fit.
Also, be sure to find a replacement solution for the TracIniMacro and
MacroListMacro before converting the docstrings that are used by those
macros, i.e. the Option docstrings and the docstrings of WikiMacroBase
subclasses (more generally, the return value of get_macro_description()
was also supposed to be wiki markup up to now).
-- Christian
John Hampton
> Noah Kantrowitz wrote:
>> Yes, this was agreed on already AFAIK. All docs, docstrings, etc will
>> be ReST.
>>
<snip>
> Also, be sure to find a replacement solution for the TracIniMacro and
> MacroListMacro before converting the docstrings that are used by those
> macros, i.e. the Option docstrings and the docstrings of WikiMacroBase
> subclasses (more generally, the return value of get_macro_description()
> was also supposed to be wiki markup up to now).
So, for all this stuff, I hope we're not thinking about using ReST.
While standardizing on ReST may be fine for the other stuff (though I
still prefer wiki markup), the IniMacro and MacroList are valuable, and
doing that documentation in ReST is stupid (inmsho)
-John
Noah Kantrowitz
Now that I can actually get to a real keyboard, I can send an email. I
am flipflopping on this and agree that anything in trac/ should stay
wiki format. ReST will be confined to things in doc/. Moving to a Py3k-
style hand-written API doc should also allow for more flexibility re:
showing deprecated uses and such, and also solves another worry I had
with moving the new docs to a branch. Sound better to people?
--Noah