Noah Kantrowitz | 14 May 14:07
Picon
Favicon

[Trac-dev] Sphinx?

What would people think about basing our new docs around the Sphinx 
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 | 14 May 14:29
Favicon
Gravatar

[Trac-dev] Re: Sphinx?


2008/5/14 Noah Kantrowitz <kantrn <at> rpi.edu>:
> What would people think about basing our new docs around the Sphinx 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?

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.

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "Trac Development" group.
To post to this group, send email to trac-dev <at> googlegroups.com
To unsubscribe from this group, send email to trac-dev-unsubscribe <at> googlegroups.com
For more options, visit this group at http://groups.google.com/group/trac-dev?hl=en
-~----------~----~----~----~------~----~------~--~---

osimons | 14 May 15:31
Picon

[Trac-dev] Re: Sphinx?


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
> > (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?
>
> 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.
>

Sphinx appeared just after getting draft 1 of the newhelp branch
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
(Continue reading)

Noah Kantrowitz | 14 May 15:45
Picon
Favicon

[Trac-dev] Re: Sphinx?

osimons wrote:
> 
> 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
>>> (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?
>> 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.
>>
> 
> Sphinx appeared just after getting draft 1 of the newhelp branch
> 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
(Continue reading)

Noah Kantrowitz | 15 May 08:03
Picon
Favicon

[Trac-dev] Re: Sphinx?

Noah Kantrowitz wrote:
> 
> 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 | 15 May 10:00
Picon
Favicon

[Trac-dev] Re: Sphinx?


osimons wrote:
> 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
>>> (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?
>>>       
>> 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.
>>
>>     
>
> Sphinx appeared just after getting draft 1 of the newhelp branch
> 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
(Continue reading)

Noah Kantrowitz | 16 May 00:40
Picon
Favicon

[Trac-dev] Re: Sphinx?

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 
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 
(Continue reading)

Gravatar

[Trac-dev] Re: Sphinx?


-On [20080516 00:41], Noah Kantrowitz (kantrn <at> rpi.edu) wrote:
>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
(Continue reading)

Emmanuel Blot | 16 May 10:01
Picon

[Trac-dev] Re: Sphinx?


+1

(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

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "Trac Development" group.
To post to this group, send email to trac-dev <at> googlegroups.com
To unsubscribe from this group, send email to trac-dev-unsubscribe <at> googlegroups.com
For more options, visit this group at http://groups.google.com/group/trac-dev?hl=en
-~----------~----~----~----~------~----~------~--~---

Picon

[Trac-dev] Re: Sphinx?


On May 16, 12:40 am, Noah Kantrowitz <kan...@rpi.edu> wrote:
> 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
...
> 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).

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
(Continue reading)

Matt Good | 19 May 19:25

[Trac-dev] Re: Sphinx?


On May 18, 2:46 pm, "rupert.thur...@gmail.com"
<rupert.thur...@gmail.com> wrote:
> 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.

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.

-- Matt
(Continue reading)

osimons | 20 May 02:00
Picon

[Trac-dev] Re: Sphinx?


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.

Moving to using the repos as master for documentation is a conclusion
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
(Continue reading)

Noah Kantrowitz | 20 May 02:13
Picon
Favicon

[Trac-dev] Re: Sphinx?


On May 19, 2008, at 8:00 PM, osimons wrote:
>
>
>
> 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.
>
> Moving to using the repos as master for documentation is a conclusion
> 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
(Continue reading)

Noah Kantrowitz | 20 May 03:01
Picon
Favicon

[Trac-dev] Re: Sphinx?


>

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

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "Trac Development" group.
To post to this group, send email to trac-dev <at> googlegroups.com
To unsubscribe from this group, send email to trac-dev-unsubscribe <at> googlegroups.com
For more options, visit this group at http://groups.google.com/group/trac-dev?hl=en
-~----------~----~----~----~------~----~------~--~---

Gravatar

[Trac-dev] Re: Sphinx?


-On [20080520 03:02], Noah Kantrowitz (kantrn <at> rpi.edu) wrote:
>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.

--

-- 
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..?

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "Trac Development" group.
To post to this group, send email to trac-dev <at> googlegroups.com
To unsubscribe from this group, send email to trac-dev-unsubscribe <at> googlegroups.com
For more options, visit this group at http://groups.google.com/group/trac-dev?hl=en
-~----------~----~----~----~------~----~------~--~---

osimons | 21 May 12:43
Picon

[Trac-dev] Re: Sphinx?


On May 20, 1:02 pm, Jeroen Ruigrok van der Werven <asmo...@in-
nomine.org> wrote:
> -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.
>

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
(Continue reading)

Noah Kantrowitz | 21 May 15:04
Picon
Favicon

[Trac-dev] Re: Sphinx?


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 <asmo...@in-
> nomine.org> wrote:
>> -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.
>>
>
> 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
(Continue reading)

Christian Boos | 21 May 17:22
Picon
Favicon

[Trac-dev] Re: Sphinx?


Noah Kantrowitz wrote:
> 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

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "Trac Development" group.
To post to this group, send email to trac-dev <at> googlegroups.com
To unsubscribe from this group, send email to trac-dev-unsubscribe <at> googlegroups.com
For more options, visit this group at http://groups.google.com/group/trac-dev?hl=en
(Continue reading)

John Hampton | 22 May 00:51

[Trac-dev] Re: Sphinx?


Christian Boos wrote:
> 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

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "Trac Development" group.
To post to this group, send email to trac-dev <at> googlegroups.com
To unsubscribe from this group, send email to trac-dev-unsubscribe <at> googlegroups.com
For more options, visit this group at http://groups.google.com/group/trac-dev?hl=en
-~----------~----~----~----~------~----~------~--~---

(Continue reading)

Noah Kantrowitz | 23 May 09:57
Picon
Favicon

[Trac-dev] Re: Sphinx?


On May 21, 2008, at 6:51 PM, John Hampton wrote:
>
> Christian Boos wrote:
>> 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)

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- 
(Continue reading)

Christian Boos | 21 May 15:24
Picon
Favicon

[Trac-dev] Re: Sphinx?


osimons wrote:
> 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:
(Continue reading)


Gmane