search

angular / dgeni-packages

A collection of dgeni packages for generating documentation from source code.
MIT License
142 stars 101 forks source link

Implementing a RAML processor #196

Closed domarmstrong closed 6 years ago

domarmstrong commented 8 years ago

There are no really good RAML doc generators currently. I'm wandering if it may be feasible to create a processor for dgeni utilising the existing RAML javascript parser. Benefits being, existing integrations and documentation for users.

Questions:

  1. Does this seem like a good idea, or is dgeni in anyways more biased/not designed for this kind of documentation over actual annotated code?
  2. Are there any high level docs explaining how to integrate a processor, or is it a case of reverse engineer something existing?
  3. Any style guides etc for the project?
petebacondarwin commented 6 years ago

@domarmstrong - sorry I never replied to this.

It looks like RAML is just a subset of YAML. So you would need to implement a YAML fileReader that parses out comments (and perhaps the structure of the data itself) into dgeni docs. Then the jsdoc package could do its work to extract additional info from any JsDoc tags found in the comments. After that you are back in standard dgeni land.

Is this something you are still interested in pursuing?

domarmstrong commented 6 years ago

No it's not, thanks. I was just exploring options at the time. I ended up writing a custom single page app that consumed RAML served by the APIs directly. This gave a real snapshot of the current state of the API without having to rebuild documentation. Since then we've moved to graphql anyway which has removed the need for RAML it has its own schema and tooling.