Hi Florian, Cool! The documentation on the website is based on Docusaurus which supports things like docs versioning. Docusaurus uses markdown files, so we rely on markdown for the documentation.
There is a 'website' folder at [1] where you can find the npm scripts to start docusaurus and a 'docs' folder which includes the documentation markdown files for the next release version (selectg "next" in the docs website). After a new release, we run a "npm ds-version" which then detects changes in the markdown files and creates a new release docs version. The documents in the "docs" folder can be freely modified and added. That's a good place where we can add new tutorials. The "pe" folder contains the documentation of pipeline elements. These are currently generated from the StreamPipes source code using the streampipes-maven-plugin (as some rewriting is needed, e.g., to fix the paths of images). This process is far from perfect and needs some manual work. It would be nice to have some Github actions script which automatically updates the Documentation, but that's a bit more advanced task I'd say 😉 If you want to make changes to the structure, this can be done in the "sidebars.json" file [3], which is also auto-versioned by Docusaurus. [1] https://github.com/apache/incubator-streampipes-website/tree/dev/documentation/website [2] https://github.com/apache/incubator-streampipes-website/tree/dev/documentation/docs [3] https://github.com/apache/incubator-streampipes-website/blob/dev/documentation/website/sidebars.json -----Original Message----- From: Florian Micklich <[email protected]> Sent: Wednesday, August 24, 2022 10:13 AM To: [email protected] Subject: Re: [DISCUSS] Documentation - Description for Adapters and Processing Elements Hello, I would also prefer a short In-App documentation and larger documentation "outside" . Personally, I prefer to read pdf documents so I can take additional notes. But HTML is also good for a quick online search.We must keep in mind what kind of documentation we want to create and should not mix them. Also, cross-references between the individual "chapters" should be avoided. This makes it easier if something should change. 1. Quick starter documentation. 2. Setup Documentation 3. Technical Documentation 4. User manual documentation with best practise I think we should hit the road and take a look along the way :) I know the in app documentation is in markdown so far?I would recommend to write the documentation in asciidoc [1] [2] This could be set up with asciidoctorj [3]. This makes it easy to include everything in Git and also keep the documentation alongside the source code. So if something is rewritten, the developer can also change the documentation. Makes new screenshots and deletes old ones.3] The creation of a PDF or HTML file can be done with Github Action. With every commit or with every release. The results can be pushed to the StreamPipes website, I guess? What do you think? Florian [1] https://docs.asciidoctor.org/asciidoc/latest/[2] German Source https://blog.ordix.de/docs-as-code-dokumentation-mit-asciidoctor[3] htt ps://github.com/asciidoctor/asciidoctorj Am Mittwoch, dem 24.08.2022 um 07:07 +0000 schrieb Dominik Riemer: > Hi, > yes, we can do both: In-app documentation which only covers the > configuration and a short description of the adapter and pipeline > element and additional step-by-step guides/tutorials with nice > screenshots that are available in the online documentation. We can > have such step-by-step guides for the most frequently used adapters. > @Florian, do you want to work on such a guide on the website? I know > you had some really good documentation ideas some while ago 😉 > CheersDominik > > -----Original Message-----From: Philipp Zehnder < > [email protected]> Sent: Sunday, August 21, 2022 1:07 > PMTo: [email protected] > Subject: [DISCUSS] Documentation - Description for Adapters and > Processing Elements Hi all, here is a new thread to discuss the > adapter documentation.Here is a link to the previous discussion in the > release thread [1]. > @Dominik I know that the registration is different, but since all > adapters already have the three files (documentation.md, icon.png, and > string.en), shouldn’t it be possible to also display the description > in the UI.How are we doing currently for the icons? > Because they are loaded dynamically as well. I think the main > difference is that the icons are loaded directly from the worker > container and not from the backend. Couldn’t we do it similarly for > the documentation file? (Please correct me if I am wrong) Regarding > the description on the Website. I think it would be great if we could > generate this based on the markdown files for each adapter. > The documentation.md files mostly describe the configuration > parameters of adapters and processors. I think it would be great to > have additional examples how to use them. (e.g. describe how a CSV > file is uploaded or how a PLC is connected). Should we include such > examples into the documentation.md file or should there be another > location for this? Any thoughts on that? > @Florian you wrote that you would like to work on the documentation. > If you need anything to start with, please let us know. > Cheers,Philipp > > > [1] https://lists.apache.org/thread/29w586db1btqo0ps1rgo3fscvt3tvrzg
