[Twisted-Python] Proposal (almost) to switch from Lore to Sphinx

[Kevin Horn]

On Tue, Nov 17, 2009 at 1:16 PM, <exarkun at twistedmatrix.com> wrote:

> On 06:00 pm, kevin.horn at gmail.com wrote:
> >On Tue, Nov 17, 2009 at 4:00 AM, lasizoillo <lasizoillo at gmail.com>
> >wrote:
> >>2009/11/11 Kevin Horn <kevin.horn at gmail.com>:
> >> >
> >> > I have written up a proposal here:
> >> >
> >> > http://twistedsphinx.funsize.net/proposal.html
> >> >
> >>
> >>In this proposal you say:
> >>
> >>Development Work
> >>  * fabric fabfile for automation of docs workflow
> >>
> >>Future Work
> >>  * This page has some stuff on using cog in RestructuredText comments
> >>to generate the output of sample scripts.
> >>
> >>The second point (in Future Work) uses cog that is integrated in
> >>paver:
> >>  * Paver allow automation of docs workflow (fabric is not needed).
> >>  * With paver you can create an bootstraped instalation:
> >>
> >>http://www.blueskyonmars.com/projects/paver/getting_started.html#but-
> >>people-don-t-have-paver-yet
> >>  * Paver is compatible with setuptools and distutils.
> >>
> >>I think that fabric is great for cluster distributions, but paver is
> >>better for manage docs.
> >>
> >>Regards,
> >>  Javi
> >For the moment, I plan to continue using fabric, for the following
> >reasons:
> >
> >- I'm already familiar with it
> >- it does what I need (run local commands, and send stuff over SSH)
> >
> >I think Paver might be very useful down the road, though.  I'll
> >definitely
> >check into it more as this project progresses.
>
> Paver and fabric and such are only significant for the conversion,
> though, right?
>
> Jean-Paul
>
>
Yes.  For right now at least, this is the case.

I think one or the other should probably be used in the future to
automate/streamline Twisted releases, since this has been a long-standing
desire of the development team (at least that's my perception...and there
are a couple of tickets in Trac about it).  This would prevent maintenance
of yet another homegrown Twisted tool to perform said automation.

But that's a discussion for another day.  Or at least another thread.

Right now I'm using fabric strictly as a (mostly) platform-neutral
alternative to shell scripts (or some other solution) to be able to convert
docs to ReST, build the Sphinx project, and deploy them to the server (sort
of...still working out some kinks) with a single command.  Once the
conversion takes place (assuming this project is successful) much of my
current need for it will go away, though it still might be useful for other
things (as I mentioned above).

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20091117/95e21f4b/attachment.html>