Hi folks, My name is Bruno Melo, I'm a computer engineering student at University of Pernambuco, Brazil. I've been doing research in the field of Machine Learning/Information Retrieval since 2005 and work (at university) with Python since 2006.
I'm very interested in develop the Documentation Production System proposed in [1] as part of GSoC and/or as a developer even without Google help... Let's talk about the project... # What? # Develop a system to make the creation and maintenance of technical documentations (books, framework documentation, etc) easier and more fun... Maintain a large collection of text and *correct* code examples isn't a trivial task. This project proposes a tool which can take working tested code from a external resource and include it inline with text [1], keep synchronized, and with references to others elements (API documentation, Trac, etc). These features can make refactoring possible, and consequently, the maintenance task easier. # How? # This system can be developed with many features, here I list some of them... *1) Extend Sphinx [2] to work like Idiopidae [3]* Example: (from http://docs.turbogears.org/1.0/ValidateDecorator) When not using forms, the story gets a bit more complex. Basically, you need to specify which validator goes with which argument using the validatorskeyword argument. Here's a simple example: @include "code/example3.py" "Root Class" *will produce something like:* When not using forms, the story gets a bit more complex. Basically, you need to specify which validator goes with which argument using the validatorskeyword argument. Here's a simple example: class Root: @expose(template="gs.templates.welcome") @validate(validators={"value": validators.Int()}) def index(self, value=0, tg_errors=None): if tg_errors: # handle the error however you want! return dict(newvalue=value*2) %% ../code/example3.py %% import turbogears from turbogears import validators, expose, validate class Root: @expose(template="gs.templates.welcome") @validate(validators={"value": validators.Int()}) def index(self, value=0, tg_errors=None): if tg_errors: # handle the error however you want! return dict(newvalue=value*2) %% *2) Links between elements.* In the above example the word *validators* could make a cross-reference to the API documentation. *3) Annotate elements in the text to make reference to elements at code example.* Example: Using the same code above, but with the preceding text a quite different: ... will return a dict with @["/code/example3.py" "index"] *newvalue* @ ... At build time if doesn't exist anything called *newvalue* at *index* method in class *Root *an error occurs. *Refactoring* *4) Generate HTML, PDF, and LaTeX output 5) Commenter system or integration with Trac* # Why? # I think that this project will be useful for both sides of a documentation system (users [developers] and producers [book/documentation writers]): For users: - read good quality documentation - read a *true* hypertext documentation - what more?? For producers: - documentation production more fun - ease maintenance - what more?? # Further reading # http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/*very good!* http://compoundthinking.com/blog/index.php/2008/03/21/documentation-tools/ # References # [1] http://docs.turbogears.org/GSoC/Ideas2008#id11 [2] http://sphinx.pocoo.org/ [3] http://www.zedshaw.com/projects/zapps/idiopidae.html [4] http://apydia.ematia.de/ What do you think?? feedbacks are welcome... Best Regards, -- bruno j. m. melo http://brunojm.googlepages.com >> brunojm <at> gmail.com << --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "TurboGears" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/turbogears?hl=en -~----------~----~----~----~------~----~------~--~---
