Tg 1.x docs in sphinx?

[Mark Ramm]

We have a script that helps export the moin moin docs into a format
that works with sphinx.

Anybody interested using sphinx for 1.x documenation? It would be
some work to clean things up after they are moved to sphinx, but I
don't think it's a huge project and I'm willing to help out.

The main benefit would I think be the elimination of doc spam that
we're currently seeing. And the tg2 docs now have a spam-free system
for comments on the docs, which would also be useful and easy to do in
a sphinxified 1.x docs system.

--
Mark Ramm-Christensen
email: mark at compoundthinking dot com
blog: www.compoundthinking.com/blog

[Felix Schwarz]

Mark Ramm schrieb:

> Anybody interested using sphinx for 1.x documenation? It would be
> some work to clean things up after they are moved to sphinx, but I
> don't think it's a huge project and I'm willing to help out.
>
> The main benefit would I think be the elimination of doc spam that
> we're currently seeing. And the tg2 docs now have a spam-free system
> for comments on the docs, which would also be useful and easy to do in
> a sphinxified 1.x docs system.

As you probably imagine, I would like seeing that. Would save me quite a lot
of time if I don't have to do a daily round in the wiki. The only thing is
that then we need another place where users can add snippets and small stuff.
I think it's quite important to have something like that.

fs

[Mark Ramm]

We could allow this in trac, or setup another system for it.

IIRC Jorge was talking about writing something specifically for
recipies. Not sure if that's a doable replacement for moin-moin in
the super short term, but I think trac isn't too bad, and it seems
that we've pretty much solved the trac spam problem at this point.

--Mark Ramm

--

[Florent Aide]

On Fri, Jan 2, 2009 at 10:31 PM, Mark Ramm <mark.mch...@gmail.com> wrote:
>
> We have a script that helps export the moin moin docs into a format
> that works with sphinx.
>
> Anybody interested using sphinx for 1.x documenation? It would be
> some work to clean things up after they are moved to sphinx, but I
> don't think it's a huge project and I'm willing to help out.

I'm +1 on this move but I need someone's help to do so :)

Florent.

[Jorge Vargas]

Yes I think a TG app for this should be a better solution. In fact I
think we should have 2 app (or instances of the same app)

1- a pastebin-like app (I plan to finish my port of spammcan to tg2 for this
2- a snips app

The difference between the two is simply the use, ideally we should
have "throw away pastes" at #1 and "important" pastes (probably with a
big rst text field) with the explanation for snips, that will serve as
mini-tutorials.

As for trac, I think that should be keep for development of TG, maybe
we could have a section equivalent to RoughDocs there using the rst
trac pages.

Bottomline, is that everyone agrees that moin-moin should be faced out
in the long term, which is great IMO.

[Christopher Arndt]

Jorge Vargas schrieb:

> Yes I think a TG app for this should be a better solution. In fact I
> think we should have 2 app (or instances of the same app)
>
> 1- a pastebin-like app (I plan to finish my port of spammcan to tg2 for this
> 2- a snips app
>
> The difference between the two is simply the use, ideally we should
> have "throw away pastes" at #1 and "important" pastes (probably with a
> big rst text field) with the explanation for snips, that will serve as
> mini-tutorials.

What the about revision control that a wiki offers? A pastebin app is
simple, but a document management system (even the most simple one), is
a bit more involved.

Chris

[Jorge Vargas]

for the most complex examples (for example wiki20 and my tgextjs
sample) I believe the repo + sphinx is the way to go.

The recepies app is for short code (less than 100 lines) which is
normally version specific, and answers quick questions, some that come
to my mind.
- how do I run trac/mercurial,etc from inside TG2?
- how do I run trac/mercurial,etc from inside TG1.1?
- how can I return json from my app?
- how to use jsnonify?
- how to write a file upload & download controller
- deployment script for webfaction
- monitoring script of paster
- integration with deliverance (this may be a little more work)
- how to enable auth-related unitests
- etc.

The point is, or my "general idea" is that everything will be stages
of complexity, where more complexity = more useful example. So for
example a quick one of will be born as a pastebin-like post, if that
provides to be very useful it will jump into a "snip", where someone
(maybe not even the original author) will write a mini-tutorial
explaining it, and probably provide more context (IE: instead of just
the controller code, add the template code to use it), and if that
turns out to be a very valuable resource then it should be migrated to
a hg repo(or svn) + sphinx source, by this point someone is probably
an active maintainer of the sample and it could/should be integrated
into the buildbot's tests to see if everything works out of the box.
Now of course the key for all this to work is keeping text formats in
sync, which is why we should use rst everywhere.

As you can tell not all examples need to go to all stages but I think
having a simple "middle ground" app is a nice thing to have and that
could be keep simple (without getting into the document management
tasks) by making sure the samples stay version specific and simple. I
think the following compromises will keep that db small, clean and
useful. (of course these are conventions not really enforced by the
app)

A snips
- it contains the following fields (think of the form) a code
textfield (maybe several for multiple file snips), a title, a
description (In rst), a set of tags, a rating.
- must be short (as I said above -100 LOC) should be a good
compromise, anything bigger deserves a repo+sphinx version.
- the app itself could have, comments on snips, a "copy snip to new"
(to track history of the snip), an ok for version x.y.z, so we could
detect broken snips with new versions and provide fixes.
- it must indicate the version it was written against
- there is no guarantee it will work with trunk/current
- it's not part of the maintenance work by tgdevs (other than keeping
spam at bay)

My idea predates, pylons new site but a good explanation of the
difference can be found on their links.

http://beta.pylonshq.com/snippets
http://beta.pylonshq.com/pasties

>
> Chris
>
> >
>