On Wed, Dec 3, 2008 at 5:54 PM, John MacFarlane
+++ Anatoly Yakovenko [Dec 03 08 17:03 ]:
This is pretty cool. I was wondering how much work would it be for gitit to be able to use markdown from the comment sections in source files? It would be a really good way to manage documentation.
Basically I would like to be able to point gitit at an existing git repo, and have it provide a wiki interface to all the documentation so developers can view and modify it.
You can do something like that now. You can specify the repository directory in a configuration file. Anything in the repository (even in subdirectories) with a ".page" extension will be served up as a wiki page. So you'd have to use a ".page" extension for your markdown documentation. Everything else in the repository will appear in the index. Source code files will be automatically syntax-highlighted, and you can even view history and diffs through the wiki interface.
cool. Does it add any other files to the reposoitory? Could you use it over a read only one?
But I guess what you want is for the documentation to be in comments in the source files themselves, not in separate files. I'm not sure how to do that -- would the idea be to show just the documentation, perhaps marked off with some special notation, and not the source? But then we lose a nice feature, the ability to view source files. I'm open to ideas.
I was thinking it would show both the documentation and the source, but have the documentation as the editable part of the page. Do you think that's possible? Or it could parse out the documentation and show 2 dynamically generated pages, one for just the docs and one for the source. But i think it would be useful to be able to see the documentation in the context of the source that its referring to. Unfortunately I am not a web guy, so i have no idea how hard any of this would be :).