Participate in DocSpec
gossi opened this issue · 5 comments
Hi,
I currently worked out a specification to make results of DocTools interoperable. This is completely new and the spec is just one day old. The idea of this spec is, that doctools deliver their output in this interoperable format and generating the output can be done by others, that don't want to work on the parsing part.
The benefits would be:
- End users can choose whatever doctool they want and which output generator they want.
- Doctool developers can focus on parsing the code, generate a standardised output and leave the output generation to the end users (doesn't that sound like less work for you?)
My blog post with my motivation for creating this: http://gos.si/blog/docspec-as-interoperable-file-format-between-doctools
As I said the DocSpec is not older than a day, you are invited to join here. Also if you feel like this idea suits your doctool, feel free to jump over to express your interesst in participating as an implementor.
The DocSpec is on github, ready to fork: https://github.com/gossi/docspec
Thank you
gossi
Hi Gossi,
This sounds like a great initiative, especially if you have a project
written in multiple languages this'd give you the opportunity to build
a single set of API docs.
PHPDoctor makes it pretty easy to add new output formats, I'd think
it'd be straight forward to add DocSpec as an output format.
Paul.
On 3 January 2012 02:30, Thomas Gossmann
reply@reply.github.com
wrote:
Hi,
I currently worked out a specification to make results of DocTools interoperable. This is completely new and the spec is just one day old. The idea of this spec is, that doctools deliver their output in this interoperable format and generating the output can be done by others, that don't want to work on the parsing part.
The benefits would be:
- End users can choose whatever doctool they want and which output generator they want.
- Doctool developers can focus on parsing the code, generate a standardised output and leave the output generation to the end users (doesn't that sound like less work for you?)
My blog post with my motivation for creating this: http://gos.si/blog/docspec-as-interoperable-file-format-between-doctools
As I said the DocSpec is not older than a day, you are invited to join here. Also if you feel like this idea suits your doctool, feel free to jump over to express your interesst in participating as an implementor.
The DocSpec is on github, ready to fork: https://github.com/gossi/docspec
Thank you
gossi
Reply to this email directly or view it on GitHub:
#58
Yes please!! Brilliant idea.
(At the moment I use PHPDoc to generate XML output, and JSDoc to generate similar XML, and then merge and render with XSLT into one set. A cleaner abstraction would be very welcome!)
That's exactly the use-case. Thanks for your words.
Sounds like a good plan. I've tried hacking phpdoctor a few times (with varying success) and having a defined output to work backwards from should make things a bit easier :)
Of course, the spec needs to be set in stone first. That's where you can get active right now.