Compodoc: [FEATURE] JSON export support

[realappie]

Could you provide us with a way to export the JSON of the documentation? I haven't looked into the source but Im sure this wouldn't be hard to implement.

I'm building a website editor where we need to provide documentation of components in a different form, and a JSON export of the documentation would help us a lot in doing so.

This would also help some other people do whatever they want with the parsed docs like generating PDF documentations in issue #190

[realappie]

@vogloblinsky Hi, I see that my feature request has been accepted which is great! But the last commit is a month ago, and there are a ton of other issues as well. Do you perhaps have an estimate on when this feature could be implemented ? Are we looking at a week timeframe, a month? a few months? Thanks!

[vogloblinsky]

@realappie
I will try to watch that this weekend.
Did you have any example or idea of the final structure of the json ?

[realappie]

@vogloblinsky Perhaps something that looks like this?

interface IApp {
    modules: { name: IModule }[]
}

Where IModule is similar looking to the module overview page

interface IModule{
  declarations: Component|Pipe|Directive[]
  providers: Provider[]
  imports: IModule[]
}

Where components pipes and directives have the similar data that is used to generate their views.

[realappie]

Hello, is there any progress on this issue? :D

[vogloblinsky]

Yes i will work on that this week. I will submit an JSON example when ready.

[realappie]

@vogloblinsky Thank you! I look forward to the JSON example.

[realappie]

Any updates on this feature request?

[vogloblinsky]

@realappie
No, it will be available in milestone 1.1.0. Output like TypeDoc does with --json will be an inspiration.
I want to fix core bugs before adding such features (JSON & PDF export)

[realappie]

The 1.1.0 milestone has been created longer than a month ago, I don't want to be pushy and would rather implement this feature my self. Pointing me in the right direction would help a lot, where is the website generated ?

[profimedica]

Hi all,
I was about to create a duplicate of this FEATURE request. Is there any progress with this? I observe JSON5 is used in development. I can try to implement this feature and suggest it as a solution.

[rdkmaster]

@vogloblinsky can you please raise the priority of the feature? we are hunger for the json exporting supported.

[vogloblinsky]

Sorry @profimedica i am inside a very long and saturated planning tunnel for one month, and it is difficult to me to work on Compodoc during my personal time.

What do you prefer ?

• big JSON with array of modules, components, etc, without link between them
• JSON with only classes, interfaces, etc, and modules (with inside compnents, directives etc) see https://github.com/compodoc/compodoc/issues/145

[realappie]

@vogloblinsky Personally, I think any form of JSON export would be a great addition. So considering the lack of time I think option number 1 is better. Remember that although you don’t have time! There are plenty of people willing to work on this feature, pointing us in the right direction would be very helpful.

[profimedica]

I forked the repository and I changed the generated file used from console.
My approach is not what people need, is a raw and incomplete JSON.
For the moment, my output at console is something like:

{ directives: [],
  injectables: [],
  routes: [],
  pipes: [],
  modules: [],
  classes:
   [ 'AgCheckbox',
     'AlignedGridsService',
     'AnimateShowChangeCellRenderer',
     'AnimateSlideCellRenderer',
     ... 43 more items ],
  components: [],
  interfaces:
   [ 'AbstractColDef',
     'AddRangeSelectionParams',
     ... 81 more items ],
  miscellaneous:
   { variables: [],
     functions:
      [ 'AngularDirectiveController',
        'applyToConstructor',
        'zeroOrGreater' ],
     typealiases: [ 'ExcelDataType' ],
     enumerations:
      [ 'ComponentType',
        'DragSourceType',
        'HDirection',
        'HeaderRowType',
        'RecursionType',
        'RowType',
        'ScrollType',
        'VDirection' ] } }

I work on integrating my function into the architecture. For the moment, it can be used or inspected on my fork at: https://github.com/profimedica/compodoc/blob/master/dist/index-cli.js

Any advice is welcomed. I will create a pull request if my solution will be approved (not the current one, but a later one).

[profimedica]

Hi @vogloblinsky , I created a first approach to export the JSON format.
I added a command parameter with a default of 'none' to make the export optional.
Other possible values are 'json' and 'simpified-json'.
The JSON object composed is sent to a new export engine that might later be used to export other formats (I am thinking of VisualParadigm diagram export).
For the moment the data is collected in a function of the application.ts
I will prepare test cases and refine the structure of the JSON.
For the moment, my approach is ready for inspection or use on my forked repository: https://github.com/profimedica/compodoc

Usage from any project:

call ./node_modules/.bin/compodoc -p tsconfig.json -e json
call ./node_modules/.bin/compodoc -p tsconfig.json -exporting json-simplified

[realappie]

@profimedica While your modification are a great step in the right direction, having more component information than just their name would be super useful.

Their inputs, methods, members and all associated JSDOC would be a great addition.

[realappie]

@profimedica I forked your repo and managed to get the components exported, I think you commented it out. Also just a tip, but if you are planning on submitting a PR I would personally clean the code a bit up and add comments here and there.

Using lodash _.forEach instead of the for loops you wrote would be a good idea as well, as its more consistent with the codebase :)

But great work on reading the code and writing something we can build on.

[profimedica]

Hi all, sory for not beeing able to respond. I had to prepare myself for a job interviw in London.
I am working on export. My code is able to export JSON, XML and DOT (graph description language used by Graphviz).

In order to export various formats and to select what nodes to include in any of them, I use a series of configurations. In the initial commit I will include Modules, Classes, Interfaces, Methods (only names and hierarchy). The scructure I am creating is very flexible, and will also permit the output to be visualized colorized on site (HTML only).

I still have to work few hours on DOT export and in the morning I will send you a Sample Output for approval.

Since tsviz is also using DOT language, this work can possible address issue:
https://github.com/compodoc/compodoc/issues/313

https://github.com/joaompneves/tsviz

https://en.wikipedia.org/wiki/DOT_(graph_description_language)

http://www.graphviz.org/

[profimedica]

This is what I prepared on a moked model: http://aju.ro/angular
I will include it on a branch, probably this is the way it has to be.

The command line options will be:
export json|xml|dot [export-configuration predefined_configuration_name|default] [export-colorized [yes|no]]

[vogloblinsky]

@profimedica Use develop branch.

[profimedica]

I created the first version of export as a new branch copy of develop.
I need guidance from now on how you want to inspect this functionality and what should I change.
Can I get credentials to push a branch ? I assume that this export functionality will increase in complexity as for now it covers XML, JSON and DOT export but other formats might be usefull or requested. I am thinking of UML Class and ERD diagrams.
A build of my branch is available at: http://aju.ro/angular/index-cli.js

[vogloblinsky]

Hi @profimedica
I am working on it for 1.0.2. We have re-written internal stuff of Compodoc and your branch is a bit behind last commits on develop branch.
I have pushed first work on develop branch, need to find the cleanest way to fix circular reference during JSON.stringify call.
Can you wait just a few days.
Thanks

[realappie]

Good to see progress being made ! I really hope the JSON export will be in such a format we can see or create a relationship between the component and its module, that would be very valuable information.

Also @vogloblinsky is there any possible the inputs of components can be parsed without the <p> prefix? Thats something you only want when displaying the data in the standard compodoc generated website, not something you would want to have when exporting JSON.

[profimedica]

Hi @vogloblinsky
My work is on most recent update of your refactored dev and is fully functional and does not use JSON.stringify.
I assume you are checking my fork that is in a very poor condition. I will delete it and update my changes.
In the morning you can review my updated version, I will also add a link to point to my commit.

[vogloblinsky]

ok thanks

[profimedica]

Just added my work over a copy of develop branch take from this morning.
I observed that my earlier wark was included and addapted in the dev. I appologise I did not knew how integration will be made, to manage my updates in git. I hope I saved your work this time.
A significant change is that export works regardless of the input parameters, for demo purpose. and I emptied the export function. I will refactir it as you need it.

https://github.com/profimedica/compodoc/commit/cb49a6219cfb481e240d25646da2f8b91ec47c9e

Usage:
npm run compodoc

Output:
./documentation/exported.html - This display colorized JSON, XML and DOT
./documentation/exported_json.txt
./documentation/exported_xml.txt
./documentation/exported_dot.txt

[profimedica]

I am investigating the possibility to cover #313 too. Any indications are helpful.

[rdkmaster]

I'm so glad to see progress being made! Thanks @profimedica and @vogloblinsky

[vogloblinsky]

@profimedica
I didn't see processDataStructure and exportAllFormats functions in your fork, did you miss to commit them ?

[profimedica]

Yes, a partial commit that morning. I committed the rest. It compiles but I have an exception when I try to use it. Here is the update.

I will have some time later today to investigate my issue:
[10:12:34] Including : C:....area.component.ts
Unhandled Rejection at: Promise {
'Error during C:\...\node_modules\compodoc\src\templates\partials\block-accessors.hbs read' } reas
on: Error during C:...node_modulescompodocsrctemplatespartialsblock-accessors.hbs read
[10:12:35] Sorry, but there was a problem during parsing or generation of the documentation. Please fill an issue on github. (https://github.com/compodoc/compodoc/issues/new)
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] compodoc: compodoc -p src/tsconfig.json
npm ERR! Exit status 1

[vogloblinsky]

@profimedica
I have pushed last work on JSON export in develop branch. Have a look and say if it seems of for you.
I will add unit test for that tomorrow.

[profimedica]

THank you. I work on this today.

[lock[bot]]

This issue has been automatically locked due to inactivity. Please file a new issue if you are encountering a similar or related problem. Why locking ? Having issues with the most up-to-date context.