tiddlywebplugins.docs

[chris...@gmail.com]

I've just finished up the first working version of a plugin for
tiddlyweb that presents auto-generated docs for each of the API
endpoints.

It does this by dynamically inspecting the system configuration and
code to show what request methods are possible and what
serializations are available.

I have it installed on TPC and TiddlySpace. Here are a few examples:

http://tiddlyweb.peermore.com/wiki/recipes/docs/tiddlers.x-doc
http://tiddlyweb.peermore.com/wiki/recipes/docs/tiddlers/validator.x-doc
http://cdent.tiddlyspace.com/search.x-doc?q=tag:cdent
http://cdent.tiddlyspace.com/HelloThere.x-doc
http://cdent.tiddlyspace.com/bags/cdent_public/tiddlers/HelloThere.x-doc
http://cdent.tiddlyspace.com/recipes/cdent_public/tiddlers/HelloThere.x-doc

(Take note of the differences betweeen the last three URIs, that
gives a good sense of what's going on the code.)

The idea is that this can help people understand what the API can do
as well as helping to package authors know when their documentation
isn't up to snuff. At the moment nobody's is, which is not that
surprising as this particular use wasn't planned.

It is however pretty useful.

It's not completely done yet but I wanted to get it out for comment.
Planned improvements or things to think about include:

* Consider if using RST in the docstrings and then doing rst2html is
appropriate.
* How to adequately represent the datastructures used for input and
output forms that are structured (e.g JSON)
* Navigation?
* I think it would make sense to put links to the canonical TPC
documentation for various resources (and from them to the x-doc).
* Document the x-doc code itself.

Having a browse at the code may be interesting if you're into
Python or TiddlyWeb guts:

https://github.com/cdent/tiddlywebplugins.docs/blob/master/tiddlywebplugins/docs.py

The package is on Python as tiddlywebplugins.docs.

--
Chris Dent http://burningchrome.com/
[...]

[Peter Neumark]

I'm impressed how little code is needed for such a cool feature!
Peter

> --
> You received this message because you are subscribed to the Google Groups
> "TiddlyWeb" group.
> To post to this group, send email to tidd...@googlegroups.com.
> To unsubscribe from this group, send email to
> tiddlyweb+...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/tiddlyweb?hl=en.
>
>

[Jeremy Ruston]

Very cool.

Some URIs I tried 404, like
http://cdent.tiddlyspace.com/bags/cdent_public.x-doc, presumably
that's because all the action happens on
http://cdent.tiddlyspace.com/bags/cdent_public/tiddlers.x-doc?

Cheers

Jeremy

--
Jeremy Ruston
mailto:jer...@osmosoft.com
http://www.tiddlywiki.com

[chris...@gmail.com]

On Thu, 3 Nov 2011, Jeremy Ruston wrote:

> Some URIs I tried 404, like
> http://cdent.tiddlyspace.com/bags/cdent_public.x-doc, presumably
> that's because all the action happens on
> http://cdent.tiddlyspace.com/bags/cdent_public/tiddlers.x-doc?

No, that's an artifact of the ControlView optimizations. See the
discussion on this (now closed) issue:

https://github.com/TiddlySpace/tiddlyspace/issues/824

Basically the optimizations make extensions on single bags not get
processed. It works okay in plain TiddlyWeb:

http://tiddlyweb.peermore.com/wiki/bags/docs.x-doc

I'm still undecided whether it is worth fixing the extension thing in
TiddlySpace as that particular loop is right in the critical path,
blah blah, etc...

[Jeremy Ruston]

> I'm still undecided whether it is worth fixing the extension thing in
> TiddlySpace as that particular loop is right in the critical path,
> blah blah, etc...

Aha, I'd say it's not worth fixing at the moment, for what it's worth

Cheers

Jeremy

>
> --
> Chris Dent                                   http://burningchrome.com/
>                                [...]
>