Improved workflow for writing/generating documentation

[jrossignol]

Right now the workflow for creating the KSP API document involves a lot of manual steps:

• Manually extracting class stubs using Visual Studio
• Manually merging changes between KSP versions (increasingly massive effort the more gets documented).

I think to be able to really push this project forward the above issues need to be resolved. My preference would be to change as little about the current workflow as possible (ie. still generate the same XML that is currently being consumed by Doxygen).

I'd like to consider using monodoc. The linked page describes two modes of operation:

1. Generate the same XML that Visual Studio/Doxygen expect from source files.
2. Generate the ECMA-335 XML format from an assembly.

The second option is extremely appealing, because it has automatic synchronization logic that will handle changes to the underlying assembly (so in theory, we'd be able to generate 1.0.5 documentation, and then run it against 1.1 and it will provide annotations in the generated document for what's changed).

The biggest drawback is that this format doesn't appear to be supported by Doxygen, so we'd have to fully commit to monodoc. The upside is that it can use the current XML instead of an assembly as input, so we could use that to generate the initial documentation (so there's a minimal effort way to get the current documentation into the "sources" we'd use for monodoc).

At some point I'll install it an run against the KSP assembly to see what the default output looks like (and maybe put it on a GitHub I/O page somewhere so people can look at it).

I won't be able to do significant work on this until my mods are all updated for 1.1, but once that's done I'll dive into this. In the meantime, I welcome comments from anyone who has strong feelings for or against this activity (or who have alternative options to suggest).

[jrossignol]

The other option that I considered was just manually writing some code to extract the info from the assembly and do the merge logic (but if monodoc already does exactly that, I'd rather not re-invent the wheel).

Yet another option if we want to preserve the doxygen side of the house is to write an XSLT stylesheet or write a script to convert the monodoc XML files into the MS C# XML format. My gut says this would be more work than just fully embracing monodoc.

[tomforwood]

Yeah I updated just a couple of classes that have changed since the first documentation was updated and it was a pain. I'll have a play with monodoc on Sunday.

[DMagic1]

I'll have to look into how this stuff actually works, but I agree in general, a better workflow would make this easier.

[tomforwood]

It looks like monodoc will make this much more maintainable in the future.
However I haven't been able to surmount a few issues yet.
1 mdoc currently crashes half was through processing Assembly-CSharp.dll. I have raised a bug with the stack trace in mono's bug system
2 mdoc can take the Assembly-Csharp.xml as a base for creating it's docs - howeverthat file hasn't been updated in 9 months and I can't update it now without getting the project to compile first which is looking hard
3 monodocer is generating files for every single class which could be overwhelming. It might be nice to have the main page feature only classes that someone has though important enough to be worth documenting

[jrossignol]

1 mdoc currently crashes half was through processing Assembly-CSharp.dll. I have raised a bug with the stack trace in mono's bug system

I'll have a look too sometime today to see if I get the same behaviour. There's also a chance that we get lucky and whatever the problem is goes away with KSP 1.1.

2 mdoc can take the Assembly-Csharp.xml as a base for creating it's docs - howeverthat file hasn't been updated in 9 months and I can't update it now without getting the project to compile first which is looking hard

My thinking is we'd just use whatever's in Assembly-Csharp.xml and then just let monodoc handle diffs as normal from there. We could call that update 1.0.x and use mdoc update -o en --since=1.0.x Assembly-CSharp.dll (at least, from reading docs, haven't tried it yet).

3 monodocer is generating files for every single class which could be overwhelming. It might be nice to have the main page feature only classes that someone has though important enough to be worth documenting

I'm on the fence on this one. I understand we want it to be approachable, but at the same time if it's not comprehensive I know that I won't use it as much (because I won't know what I'm missing). Personally, I vote for just having everything (even if a lot of it has no documentation).

[jrossignol]

Found your bug report (39394) filed against Mono. I got the same error when I tried to run it. Unfortunately, it looks like there's no way to get it to either run against specific classes, or exclude specific classes.