On Jun 29, 5:42 pm, OzzyB wrote:
Hey everybody,
Thanks for the warm replies. :)
> 1) If the problem with Tipfy as it currently stands, is "simply" a
> case of documentation, then we can work on it and sort it out. So if
> the question is having someone "take the lead" and go through and
> rewrite/tweak the documentation, then I would be happy and willing to
> do so and in turn invite others to give input in an open way too.
That would be great.
> I would ask you however to give me some pointers in how to best format
> the text/docs correctly -- are we using Sphinx? Is that the way to go?
Sphinx is the way to go, and a quick start would be to organize the
API documentation - just create sphinx files to document classes and
functions (using autodoc). The tipfy source code is fully documented
in restructured text format already, and so it is ready for Sphinx and
this would be just an organization work.
Once the API is organized, which should not take a lot of time since
the API is already documented in the source, at least we have some
updated docs.
Then narrative docs could be added gradually, and this takes a bit
more time to write. If you wish, documentation could be adapted from
webapp2 -- many things match -- or it could be used as a start point
to define the main topics to be covered (WSGI app, routing, handlers,
request etc).
> etc. I would also assume that adding this well-formatted docs/text to
> the actual source-code would allow us to generate whatever kind of
> html documentation we need... also please remember that I'm not saying
> I'm the best documentation writer in the world, but I *know* English
> and I'm willing to give it a shot if you think that can help us push
> forward.
Relax, any help is welcome and I really appreciate it.
> Now, if the problem (maybe) is "making the switch" from the old 6.x
> version of Tipfy to the new 1.0 release, i.e. in terms of the actual
> online documentation at Tipy.org. Then my suggestion -- eventhough it
> may be unpopular -- is to make a "reset" of all the (online)
> documentation, with the new Tipfy 1.0 docs set as the default.
>
> I would imagine trying to maintain 2 versions of docs with 2 versions
> of the codebase is quite difficult and stressful. I would *like* to
> think that current Tipfy developers would understand this and be
> proficient enough in Python etc. to weather this switch-over.
Agreed. Forget old versions, stick 1.0 to the wall.
> Now, if you really feel that Webapp2 is the way to go for a happier
> future in developing for GAE -- because of it's better routing etc.
> Then I would urge you to consider replacing Werkzeug's Routing with
> Webapp2's (or whatever it is!), and in a sense, create a new and
> improved Tipfy rebuilt ontop of Webapp2.
Armin said he will work on improvements in werkzeug routing, which is
great as it is but lacks behind in domain/subdomain routing. So I'd
suggest to wait for it. The webapp2 routing system has purposely less
features than werkzeug's (werkzeug.routing has the same size of the
whole webapp2), and it is perfectly capable for webapp2 but would be a
loss for tipfy users (and would raise unneeded compatibility
problems).
> 3 (optional) If you are just sick and tired of Tipfy and just want to
> move on, I understand, and I don't think anyone will fault you for it.
> I have seen this "version 2.0 dilemma" before and have even
> experienced it myself, so I hear ya...
Yeah, well, currently tipfy embarrasses me a bit because of the state
of the documentation. I just have little energy to do it myself, and
so I should at least be clear about this to get rid of this
embarrassment and let others join to move forward. I'd be proud again
if this was improved and could help. :)
> In fact I would be happy to buy Tipfy from you, as it is, for $1 --
> because as it stands, even if there are no future updates, I think it
> is a great little project :)
$1? /cry ;)
Please ozzy, talk to others that manifested interest to help, and
reach me on IRC and let's coordinate the documentation effort.
Thanks everybody for the support.
-- rodrigo