Feature: Generate API documentation

[pandauxstudio]

Would be nice to generate searchable documentation of the code in similar style to http://api.highcharts.com/highcharts or http://api.silverstripe.org/3.3/!

[Firesphere]

Do you know of a nice docblock parser? As with a hook to external API's, integrating it in here would steer away from the core functionality.

[axyr]

I agree with Simon.

[camfindlay]

We've been using this at SilverStripe for ages, it's pretty useful http://www.apigen.org/ - the SilverStripe CMS API docs at https://api.silverstripe.org are generated using this.

[Firesphere]

APIGen seems to work, but not to my personal satisfaction. It's not always picking up the tags between the constants.

[axyr]

This is really an IDE helper.
Generation API documentation goes further then creating docblocks for DataObjects so an editor recognise them.

I guess a seperate module would be justified for that.

[Firesphere]

Agree with @axyr. I guess it should be separate. The only possibility would be to integrate triggering a new doc-generator. But even that's quite out of scope after trying a bunch of generators.

[Firesphere]

In addition. A generator-module would be nice, where any module (including this one), could call DocGenerator::generate(); for example, and have the generator module figure out what/how/when/where the docs should be generated.

[Firesphere]

I'm going to reopen this. Using apigen, this is very easily implemented with very little effort.

I think it has added value, since my branch with doc-generator included only took about 6 lines of code to make it work.
This module is about helping, and just 6 lines of code with implementing flushable, I think it's worth having a look at.
Having it disabled by default and suggesting to install apigen would lead it to be maybe 10 lines of code. Why not implement it?

[axyr]

Because it is out of scope and I don't want to maintain it.

Who reads generated API pages anyways. It just clutters the Google search results when searching for meaningful information about code.

I still need to see an API page generated from code, that is more readable then the code itself (should be)...

[Firesphere]

I'm actually unsure if it's really that out of scope. I'd like to see how the interest in this might be going. I'll keep the docs up to date and see where it leads to.
As I pointed out earlier, I do agree on it being out of scope. But also, it's minor effort, so why not let the users decide?
Also, a lot of intermediates like APIdocs. Or have some sort of insight into how the system works.
Maintenance will probably be low, since I doubt APIGen will break their implementation soon... It's basically run-if-available.

I'll see if I can use the extend methods to make it more plug-and-play instead of direct implementation, but I do think you're being too strict here 😉 (That's why I re-opened the issue)

[axyr]

An API generator can exist without this IDE annotator and vice versa.
I would opt for a separate module, so users can pick what they want.

In my opinion generating API pages based on doc blocks is something different, then generating doc blocks to make it easier to work in an IDE.

Sure, both have something to do with doc blocks, but that's all they have in common.

So better write something separate, that can maybe merged later on then to have it removed from the idea annotator..

That it is easy to add, does not mean we should do it.

[Firesphere]

I agree to the "easy does not mean we should" :)

Maybe we need/want to add hooks, something like onAfterAnnotation?

[Firesphere]

I've partially started working on a documentation module which relies on IDEAnnotator to generate "good" documentation.
This one can be closed. I'll create a repo when I'm happy with the results of my work.