impress / impress.js

It's a presentation framework based on the power of CSS3 transforms and transitions in modern browsers and inspired by the idea behind prezi.com.

http://impress.js.org

MIT License

37.62k stars 6.67k forks source link

Plugins documentation / getting started guide #835

Closed janishutz closed 1 year ago

janishutz commented 1 year ago

I collected documentation for all the plugins and added documentation, where it was still required. I will be adding these to the wiki as well.

janishutz commented 1 year ago

I am currently working on an actual website for impress.js

janishutz commented 1 year ago

I still need to work on the table of contents, I forgot about that.

janishutz commented 1 year ago

added that

fnogatz commented 1 year ago

Hey @simplePCBuilding. Thank you for the effort you put into this. I'm skeptical about the structure it introduces regarding plugins. As of now, each plugin is treated separately in its own subdirectory within src/plugins. Some directories contain only the plain JavaScript file, others also include their own README.md. I would suggest to stick to this structures as it makes it easy to separate concerns. In the long term, plugins can be easily added as new directories without any additional maintenance burden to keep the global README.md or GettingStarted.md consistent. In addition, some might even be pulled out into their own repository. So I would be in favor to just create new README.md files in the subdirectories of src/plugins where they are currently missing.

@henrikingo, what's your opinion on this?

janishutz commented 1 year ago

Only did this because it was requested in an issue.

fnogatz commented 1 year ago

You are probably referring to #831. What is the difference between the two pull requests #831 and #835?

janishutz commented 1 year ago

831 is a general Getting Started guide for people creating an impress.js presentation for the first time. #835 is for Plugins getting Started (so just collection of all README.md of the Plugins)

henrikingo commented 1 year ago

@fnogatz thanks for helping out with reviews!

Yes so I have feedback on 2 levels here:

I don't think a Getting Started guide should just dump all the plugin documentation at the end. What you have in #831 is the right approach. Show the basics, and a few of the most useful plugins, and that's it.
As @fnogatz said, there's a reason why the docs for each plugin are in the plugin's own folder. They are best maintained that way. From here, there are 2 things that could improve:

Add a README.md file for each plugin. Many only have source code comments currently.
Create some automated build script, that is called from build.js, that collects all of these into a single easily readable documentation. This could be as simple as generating a file /src/plugins/TableOfContents.md automatically. (Just like /examples/index.html is generated.)

janishutz commented 1 year ago

Sure, I'll do that. I'll probably also clean this branch here with that. I'll just add a simple getting started here.

janishutz commented 1 year ago

I have a way better solution for this with the website. I'll add README's to all plugins that don't have any yet

janishutz commented 1 year ago

I have solved both your ideas with two different approaches.

I have created the README's in this PR
I have created a build script that automatically builds DOCS (on website) from the MD sources and converts it to HTML. I will soon open a PR for that