New option for automatically generating class diagrams

krisztianb commented 4 years ago

Hello Meir,

I created a fork that adds an option to your plugin. When the option is present the plugin automatically creates UML class diagrams for all classes and interfaces.

I've seen that a lot of people want this feature, but currently no doc generating tool for TypeDoc is able to automatically generate class diagrams. Your plugin let's us add all kind of UML diagrams to comments.

But since the code defining the class hierarchy is already in the source code:

class B implements A

It should not be necessary to write something like this yourself:

<uml>
  interface A
  class B
  A <|.. B
</uml>

What do you think?

PS: I also looked at the extension @0815fox created. But since it is unfinished, was not working correctly sometimes and modifes your plugin hard, I decided to create my own simpler extension instead.

Future plans include:

Moving to the new plugin syntax that you were mentioning in the other issue
Moving from JavaScript to TypeScript

Example UML output:

UML example

krisztianb commented 4 years ago

Update:

I moved to the new plugin syntax. TypeDoc is going to drop the decorator pattern (I asked them on Gitter), so the plugin is now loaded using a load function.
I converted the entire code from JS to TS.
Also: I noticed that a lot of the code can be reused in other plugins. So I created a repo called typedoc-plugin-base that this plugin is now using.

krisztianb commented 4 years ago

I read your message, which you seem to have removed. 😄

Please take your time to review the changes.

I must admit that I completely ignored your tests section of the repo. I have no idea if the tests are still working. Unfortunately I have no experience using testing frameworks with JS/TS.

But, I almost entirely left your old code the same it was. The only thing I changed was to subscribe to the resolveEnd instead of the resolveBegin event of the TypeDoc converter. The reason is that the new class diagram feature needs to access the reflections of the types which are not available (yet resolved) at the beginning.

I added some more options in the last couple of days and some more are still planned. Mostly formatting things (specifying background-color, font-family and the like) for the class diagram feature.

krisztianb commented 4 years ago

I finished adding the options that I found reasonable. I tested each option on its own.

Here is an example output using some of the options:

I also updated to the latest TypeDoc and TypeScript versions. They seem to be pretty busy changing stuff that is unfortunately going to break most of the old plugins.

yboujraf commented 4 years ago

@krisztianb do you have the npm link to download your repo. I tried to use with npm install but all your properties didn't work ;-)

Best Regards Youssef

krisztianb commented 4 years ago

@yboujraf I haven't deployed it on npm yet. I wanted to wait and see what @meirgottlieb has to say about it. But it looks like he is not really interested in the project any more? He did reply here, but deleted the post afterwards.

Actually I'm planing to remove the typedoc-plugin-base dependency first. After that I could put it on npm for everybody to use.

yboujraf commented 4 years ago

@krisztianb

Thanks for your feedback.

It is just missing this option to close my technical documentation and it will be great if you could share short time to implement it.

I tried by replacing this in package.json but nothing :

package.json

"scripts": {
"docs:class:diagram": " rimraf ./docs && typedoc --options ./typedoc-config-class-diagram.ts"
}

I replaced the Version coming from npm.org. I did for many others repo for other project but here no result

    "devDependencies": {
"typedoc-plantuml": "https://github.com/krisztianb/typedoc-plantuml.git"
}

and npm install. Graphviz is installed without error.

running my script

$ npm run docs:class:diagram

> @by-research/smh-template-connector-lib@0.0.0-development docs:class:diagram C:\Git\by-research\smh - connectors\smh-connector-lib\smh-template-connector-lib
>  rimraf ./docs && typedoc --options ./typedoc-config-class-diagram.ts

Loaded plugin typedoc-plantuml
Error: Tried to set an option (umlClassDiagramType) that was not declared.
Error: Tried to set an option (umlClassDiagramPosition) that was not declared.
Error: Tried to set an option (umlClassDiagramHideEmptyMembers) that was not declared.
Error: Tried to set an option (umlClassDiagramTopDownLayoutMaxSiblings) that was not declared.
Error: Tried to set an option (umlClassDiagramMemberVisibilityStyle) that was not declared.
Error: Tried to set an option (umlClassDiagramHideCircledChar) that was not declared.
Error: Tried to set an option (umlClassDiagramHideShadow) that was not declared.
Error: Tried to set an option (umlClassDiagramBoxBackgroundColor) that was not declared.
Error: Tried to set an option (umlClassDiagramClassFontStyle) that was not declared.
Error: Tried to set an option (umlClassDiagramClassAttributeFontStyle) that was not declared.
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! @by-research/smh-template-connector-lib@0.0.0-development docs:class:diagram: ` rimraf ./docs && typedoc --options ./typedoc-config-class-diagram.ts`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the @by-research/smh-template-connector-lib@0.0.0-development docs:class:diagram script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\ybouj\AppData\Roaming\npm-cache\_logs\2020-04-29T23_53_51_497Z-debug.log

typedoc-config-class-diagram.ts

module.exports = {
    inputFiles: ['./src/'],
    mode: 'file',
    includeDeclarations: true,
    tsconfig: 'tsconfig.json',
    out: './docs-class-diagram/',
    excludePrivate: false,
    excludeProtected: false,
    excludeExternals: true,
    readme: './README.md',
    name: 'Probel SW-P-8 protocol Library project',
    ignoreCompilerErrors: true,
    plugin: 'typedoc-plantuml',
    listInvalidSymbolLinks: true,
    entryPoint: 'index',
    categorizeByGroup: true,
    media: './medias',
    version: '',
    gitRemote: 'remote',
    gitRevision: 'revision',
    theme: 'default',
    umlLocation: 'local',
    umlFormat: 'svg',
    umlClassDiagramType: 'detailed',
    umlClassDiagramPosition: 'above',
    umlClassDiagramHideEmptyMembers: 'false',
    umlClassDiagramTopDownLayoutMaxSiblings: 6,
    umlClassDiagramMemberVisibilityStyle: 'icon',
    umlClassDiagramHideCircledChar: 'false',
    umlClassDiagramHideShadow: 'false',
    umlClassDiagramBoxBackgroundColor: 'transparent',
    umlClassDiagramClassFontStyle: 'bold',
    umlClassDiagramClassAttributeFontStyle: 'italic'
};

Finally, the issue section in your repo is closed.

Thanks in advance

Best Regards, Youssef

krisztianb commented 4 years ago

@yboujraf thanks for the info. I activated the Issues section in my fork.

To get my changes working you could do the following: (Let's say that the location where you are already running typedoc is A)

Download my fork or GIT clone it to you computer to location B
Do an "npm install" at B to setup node and get the dependencies
Compile the plugin (e.g. "npx tsc" in cmd.exe) at B
Delete the files at A/node_modules/typedoc-plantuml
Copy all files from B into A/node_modules/typedoc-plantuml
Copy all dependencies listed in B/package.config from B/node_modules/ to A/node_modules/

Now you should be able to run typedoc with the new options at A.

yboujraf commented 4 years ago

Dear @krisztianb

Will try it and let you know.

Best Regards, Youssef

krisztianb commented 3 years ago

Closing this issue. My plugin for generating class diagrams can be found here: https://github.com/krisztianb/typedoc-umlclass

artifacthealth / typedoc-plantuml