5 ms·
Pocco: Python port of Docco (literate-programming-style documentation)
- warp 16y agoIt's an interesting approach, and might make you more inclined to write documentation -- as it is less hassle to do so. But the end result isn't very readable, the text ends up being an API reference disguised as something else. I prefer a "literate testing" approach, where you mix documentation with doctests. It's easier to tell a story when you show the reader what your API does, instead of its internals. And you will never have to worry about keeping the examples up-to-date with your code if you make them doctests.
- gmaster1440 16y agoHow would i be able to add the comments on the left? So far, i was only successful in generating the source code on the right.
- mnemonik 16y agoWhat language are your source files in? Python, Ruby, Scheme, Lua, and CoffeeScript should all be supported (but it doesn't play nice with /* */ style JS, just //). All code comments that are on their own line should become documentation on the left, for example: # This should become docs def this_is_the(code): ... Take a look at the raw file on github, and compare it to the generated file: http://github.com/fitzgen/pocco/blob/master/pocco http://github.com/fitzgen/pocco/blob/master/pocco
- mnemonik 16y agoOh hey! This is my project! (Actually its really Jeremy Ashkenas', I just ported it to Python). Please fork it on GitHub and make it cooler!