Participate in DocSpec #58

Open
gossi opened this Issue Jan 3, 2012 · 5 comments

Projects

None yet

4 participants

@gossi
gossi commented Jan 3, 2012

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

@peej
Owner
peej commented Jan 3, 2012

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

@nickdunn
nickdunn commented Jan 3, 2012

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!)

@gossi
gossi commented Jan 3, 2012

That's exactly the use-case. Thanks for your words.

@DerManoMann
Contributor

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 :)

@gossi
gossi commented Jan 3, 2012

Of course, the spec needs to be set in stone first. That's where you can get active right now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment