This is somewhat historical at this point, but a number of links on the kamaelia site are bust and the docs generation is currently non-functional. There's a lot of (now somewhat irrelevant) reasons for this, but it would be nice to fix.
One of the best ways of dealing with this is to redo the way the component generation takes place.
In particular -
Get Kamaelia Components to generate their own documentation. This would allow the website docs to be simpler. 95% of the work to do this already exists, but going the final step would probably be a good idea.
Also, this is doable because all the docs in kamaelia are written and intended to be machine readable in the first instance.
The only thing necessary to make that work is to ensure that importing a kamaelia modules does not do any work, and that instantiating a kamaelia object doesn’t do work. But it might be just sufficient to import the module rather than create instances.
Most of the internal docs are currently RST, but it would be nicer if they were markdown. This is akin to asking the classes and modules to generate a __str__ but suitable for external docs, so perhaps add a __markdown__ method (or function) to classes and modules ? That then allows a number of option and having some standard functions for generating aspects of API docs.
This is somewhat historical at this point, but a number of links on the kamaelia site are bust and the docs generation is currently non-functional. There's a lot of (now somewhat irrelevant) reasons for this, but it would be nice to fix.
One of the best ways of dealing with this is to redo the way the component generation takes place.
In particular -
Get Kamaelia Components to generate their own documentation. This would allow the website docs to be simpler. 95% of the work to do this already exists, but going the final step would probably be a good idea.
Also, this is doable because all the docs in kamaelia are written and intended to be machine readable in the first instance.
The only thing necessary to make that work is to ensure that importing a kamaelia modules does not do any work, and that instantiating a kamaelia object doesn’t do work. But it might be just sufficient to import the module rather than create instances.
Most of the internal docs are currently RST, but it would be nicer if they were markdown. This is akin to asking the classes and modules to generate a
__str__but suitable for external docs, so perhaps add a__markdown__method (or function) to classes and modules ? That then allows a number of option and having some standard functions for generating aspects of API docs.