Documentation Generator for Monkey?
Monkey Forums/Monkey Programming/Documentation Generator for Monkey?
| ||
| So Diddy hasnt got the best documentation (least it got some :P), so I was thinking about code documentation and just generate it from there. In the past I've quickly looked at bbdocs for BlitzMax, but didnt really use it as I never shared code so I didnt have to do the doco. Is bbdocs usable for Monkey? Or should we use Ziggy's new one? (BTW Ziggy I remember seeing a webpage where you show an example, but I cannot find it now?) Cheers! |
| ||
| jungle ide documentation shows how it should be used and also the fontmachine sources have it. you can take a look there. it's similar to blitz makedocs but with some improvements. Its simple but easy to use and integrates on Jungle Ide intelliprompt automatically. |
| ||
| Didnt you write a blog post with some screenshots? |
| ||
| this is the post I did when this was going to be released. I supose thats the post you're talking about http://www.jungleide.com/?page_id=33/jungle-ide-group4/general-discussion-forum5/im-working-on-a-doc-generator-for-modules-first-screenshot-thread154 |
| ||
| Yep, thats the one :) Thanks! Just looking now, actually... Diddy isnt a solution, so how can I build the entire documentation without doing file by file? |
| ||
| You can't, you have to do it file by file, or as a solution. The way to work with multiple files on Jungle is solutions, so it was the most sensible way to support multi-file doc generation. I may add a way to document "all open documents", it should not be very complicated and if it's going to make your life easier, just tell me and I'll add this |
| ||
| Hi, I'm also working on an automated doc system, although it'll be based on doc files that are separate to the source code and potentially wiki based. Perhaps later it'll be expanded to extract in-source docs too, but I wanted to avoid docs in source this time around as that makes them harder to maintain (IMO). I *do* want to open the wiki up eventually to more people - possibly everyone - but not until this stuff is worked out, and some kind of editing/approval system put in place. Just letting everyone go nuts with the wiki doesn't seem sensible... My goal is to basically come up with something like this... http://doc-snapshot.qt-project.org/4.8/qmainwindow.html ...which I've really been enjoying using lately. It shouldn't be hard to tweak it too provide different layouts, and css will allow you to do a lot with styling, but it will initially be a fixed 'page per scope' system - ie: each module AND class will have it's own page. The wiki will change to this format too. The actual docs will need to be in a wiki-ish format, but you'll also be able to use html in-line for lists/tables etc. I should have something out soon, but I thought I'd mention this now given there's a potential conflict with Ziggy's work, although I'm sure Monkey can handle having multiple doc systems! |
| ||
| I may add a way to document "all open documents", it should not be very complicated and if it's going to make your life easier, just tell me and I'll add this Please :) |
| ||
| I should have something out soon, but I thought I'd mention this now given there's a potential conflict with Ziggy's work, although I'm sure Monkey can handle having multiple doc systems! We'll see how it all goes but I'm pretty sure it should be ok to support both systems as the one currently included in jungle Ide and in Junlge Lite do use a specific folder to build the documentation and it is separated from official documentation folders. When someone press F1, the IDE will look for documentation in a cascade way, so it will display the first available documentation in any of the provided systems. It would be great if Ted can also look for documentation created using Jungle in its browser. It should be altra easy, all pages are in a module subfolder called .docs, and all you have to do is reference the file:[modulelocation].docs/modulename.monkey.html#ItemName As an exmample, this shows documentation for the class BitMapChar in my computer: file:///C:/Monkey%20Compiler/MonkeyPro60/modules/fontmachine/.docs/bitmapchar.monkey.html#BitMapChar And this shows documentation for the method LoadCharImage: file:///C:/Monkey%20Compiler/MonkeyPro60/modules/fontmachine/.docs/bitmapchar.monkey.html#LoadCharImage You can also add the sourcecode linenumber of the identifier declaration: file:///C:/Monkey%20Compiler/MonkeyPro60/modules/fontmachine/.docs/bitmapchar.monkey.html#28LoadCharImage This way you can avoid name clashes on overloading, or several classes defining the same methods on the same document. This system is simple but very easy to use. |
| ||
| In terms of docs, I have an almost working AJAX search plugin for the wiki system Monkey is currently using for its docs. Basically, it works for me but it would need some extra work doing to it so that it's easy for you guys to integrate. Basically, it uses the wiki index to generate the AJAX intellisense search field. It is included on each page with a small snippet of code. Is there any interest in me making that public? |
| ||
| I'm also working on an automated doc system, although it'll be based on doc files that are separate to the source code and potentially wiki based. I should have something out soon. Makes me happy! At last! :) There are so much good information on this forum and on monkey blogs but that information is not always so easy to extract at the time it is needed. And with a official doc-system and all the great people in this community I'm sure we will soon have a really solid knowledge-base. Also superb for custom frameworks like Diddy and the many others! @Ziggy, I think your in-code system will work very nice together with an official stand-alone wiki system. Only improvement I'd like to see is not needing to write "summary:" before my comments - would also make it much easier to create docs from code that was created without the thought of a specific doc-system. And generate from current open docs, I'd like that too! |
| ||
| Ziggy's docs can be really cool , http://dev.cruel-gaming.com/docs/Terminal2/index.htm was made with Jungles doc system, I only had to make the frameset and the nav links, but thats something I have requested on the jungle forums, so with any luck Ziggy will make it export a frameset and links. |
| ||
| Taipoz, nice! While I'm not that fond of frames I'd have to say it was a smart simple working solution. |
| ||
| I love that example. And I think the frames work great in this situation. I would love to see all of Monkey's docs and Diddy in that format. |
| ||
| Yeah its nice, I use it a lot, if Ziggy does not add it to Jungle I plan to write a parser of my own to parse the docs jungle produces and have it make the links and framset so all I need to do is export the docs, then double click an exe, and bingo, nice easy to read, themed if needed, docs :) |
| ||
| I plan on adding an indexing system to the current docs system. It's in the todo list and should come soon. |
| ||
| cooolll...!. |
| ||
| I had a look at Ziggy's docs and found them a bit lacking. I don't mean this as an insult, just that it's in an early stage and missing features such as Taiphoz has mentioned above. The integration with Jungle is quite good, but the exported html docs are quite basic, though improved by "borrowing" the frameset code from Taiphoz ;) I started looking at using doxygen as a potential alternative, at least until Ziggy's docs had some of the extra functionality. At first, it didn't seem viable as it only supports C-style languages unless you write a filter for it. Then I considered that the trans does exactly what the doxygen filters are supposed to do: convert code from one format into another. Ok, so I'm nowhere near that stage yet, but I translated some files by hand so they were kinda C-style, so I could see what it would potentially look like. The results of my test can be seen at http://kaldev-games.co.uk/helix/, which IMHO looks quite useful, albeit a bit of a pain if it has to be hand-translated each time. I'm considering delving into the trans code to see if it's feasible to create a "doxygen" target that'll do all this automagically, but I really don't have a clue what awaits me :P I know this style of documentation may not suit everyone here, but I thought I'd share my findings just in case. If others are interested, I'm more likely to look at creating a doxygen target and sharing it. If I'm the only one who cares, it's probably best I stick with hand-translating. |
| ||
| I had a look at Ziggy's docs and found them a bit lacking. I don't mean this as an insult No worries! hehehe. I know they're very basic now. I needed something functional for the fontmachine documentation. They will be improved soon-ish But I have the idea of keeping them simple and easy to use. My first idea is that you could provide a "documentation.txt" page on any project that can contain directives on how you want to organize the documents index, so when you build documentation for that project, the idex is also created. I think with this it'll be enough. I plan to support bcodes on this index page, so it can be customized. But I'm still "designing" all this so it may end being different. |
   |