On Jan 28, 2011, at 10:51 PM, Kevin Horn wrote:
> right now the API docs aren't a lot of help for older code, and most of the
> core things are older code.
And that's exactly the problem - I don't want to paper that over with a shiny
new project to explain everything in some new location. I want to fix the API
docs.
> And that assumes there is an interface for whatever abstraction I'm looking
> for.
If there aren't, that's a failure of the implementation, so let's fix that :).
But, okay,
> I spent several hours once upon a time sifting through the API docs and
> source trying to figure out what (Cred) Avatars came with Twisted. Some
> abstractions don't come with source code.
Yeah uh, okay. The cred docs are bad and at this point I don't think that
anyone except me (and maaaaaybe exarkun) understands them. This is a bit of an
unrelated problem. The abstractions do have source code, and could be better
explained. And it needs narrative documentation,
> One of them (at least) is to fix the current glossary, since it's current
> state is DISMAL (It has links to the API docs everywhere though).
Man, there's a current glossary? (*opens glossary.xhtml*). Oh my goodness.
Yes, that's not great. And yes, please, fix it up.
So again, as the person actually doing the work, you can obviously put your
effort wherever you think it's most valuable, but really everything boils down
to this: rather than have "a paragraph of discussion" in the glossary, save the
discussion for the narrative documentation or the API documentation, as
appropriate. Feel free to edit the API docs or the narrative docs to have good
things to link to.
> It is currently not possible (AFAIK) to link to things in the long-form docs
> from the API docs in any kind of maintainable way. There's a ticket for this
> (#2801). I have some ideas for how it might be fixed after the Sphinx
> conversion is done. I have zero idea how it might be done before that. You
> could put in static hyperlinks in the API markup, but that would be highly
> subject to breakage.
Well, let's get that migration done then! hut, hut!
_______________________________________________
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
