Create documentation website

[balazsbotond]

The API documentation should be generated instead of being hardcoded in the README.

We need to find a tool that produces nice-looking API docs easily and also allows adding additional pages.

[harshilparmar]

@balazsbotond what about storybook https://github.com/storybookjs/storybook

[balazsbotond]

@harshilparmar if I understand correctly, storybook is for developing UI components in isolation. What I'm looking for is something that would fetch the jsdoc comments from the code and convert them to nice-looking, simple html documentation.

[praveen5959]

There is jsdoc. We can use jsdoc command to generate HTML. https://github.com/jsdoc/jsdoc

Here is an example: https://github.com/danyg/jsdoc3Template/wiki#screenshots

We can try this.

[harshilparmar]

@harshilparmar if I understand correctly, storybook is for developing UI components in isolation. What I'm looking for is something that would fetch the jsdoc comments from the code and convert them to nice-looking, simple html documentation.

Ohhh, that's cool thing. I have never heard something like that 👂

[balazsbotond]

@praveen5959 this is what we need, thanks 👍

[balazsbotond]

@EngrKhizarIqbal would you like to do this one?

[EngrKhizarIqbal]

You are right. StoryBook is for UI testing not for generating docs. jsdoc or any other library that generates nice and clean HTML from javascript docs will serve our needs.

[EngrKhizarIqbal]

But one thing, as I know, JSDoc will only extract documentation from the comments developer write in the code. However, we might want to explain more some parts of the app or add multiple examples for a single method, doesn't this long comments in the code make the file big (with tens of line of comments, for a method that has 3-5 lines of code)

Instead, in my opinion, we should some tools like docsify to generate HTML files out of MD files.

I never used JSDoc, so might be my point is invalid or JSDocs allows us to do so but we have to keep this in mind too.

[balazsbotond]

@EngrKhizarIqbal you're right, generated documentation isn't very friendly and we could indeed write better docs manually. I originally wanted to use the jsdoc comments already in the code because of how easy it would be but you've convinced me :)

Thanks for suggesting docsify. I took a look at it and it looks like an excellent tool and it can be used very easily with GitHub Pages.

I would still keep the jsdoc comments in the code to provide documentation popups in VS Code but let's use docsify for the website.

Would you like to start working on it? I think a good first step would be to split the README into multiple .md files and use those as input for docsify. Later we could rewrite it to include more info.

[EngrKhizarIqbal]

Yes, JSDocs are indeed necessary for IntelliSense info and we can't opt them out. I'll work on it.

[balazsbotond]

Thank you!

[balazsbotond]

You can put the .md files in the docs folder. Please keep the two .svg files there - the README uses them and the documentation should also reference them.

[EngrKhizarIqbal]

Got it. Will check the MD files and start working on it from tomorrow since I'm almost done for today.

[balazsbotond]

Thank you!

[balazsbotond]

@all-contributors please add @praveen5959 for ideas

[allcontributors[bot]]

@balazsbotond

I've put up a pull request to add @praveen5959! :tada:

[balazsbotond]

@all-contributors please add @EngrKhizarIqbal for ideas

[allcontributors[bot]]

@balazsbotond

I've put up a pull request to add @EngrKhizarIqbal! :tada: