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!