Hi Florian, I am not sure if we will find many available public data sources, especially for PLCs. But maybe we find some docker containers that can be used for the tutorial. If we do not find some, maybe we can provide them in our registry. We could also use them for the automated tests. That would be great, because currently those tests are not integrated in the nightly run.
I think for most users it is already helpful to have a working example for the different adapters, so they do not necessarily have to try out the examples. As you said we should collect all the information somewhere. Should we use thwiki for that? Cheers, Philipp ________________________________ Von: Florian Micklich <[email protected]> Gesendet: Samstag, August 27, 2022 1:20 AM An: [email protected] <[email protected]> Betreff: Re: [DISCUSS] Documentation - Description for Adapters and Processing Elements Hi, perfekt, I will create this branch. I will think about a possible structure over the weekend. I let you know. How are you testing and using the adapters and wich one are you using most? Do you have some URL sources you always for developing process or testing and what is the typical workflow to add them?Maybe we can start to collect them in some way so I can add them later in the documentation. GreetingsFlorian Am Donnerstag, dem 25.08.2022 um 19:38 +0000 schrieb Dominik Riemer: > Sounds good!We usually use only the issue name as branch name > (STREAMPIPES-581) without the "feature" prefix, but both is totally > fine! > Dominik > > -----Original Message-----From: Florian Micklich <[email protected] > > Sent: Wednesday, August 24, 2022 9:44 PMTo: > [email protected] > Subject: Re: [DISCUSS] Documentation - Description for Adapters and > Processing Elements > Hi Dominik,thanks for the answer and before I ask more questions, > I'll simply start :-)Therefore I created a ticket > https://issues.apache.org/jira/browse/STREAMPIPES-581 > I will also create a feature branch feature/STREAMPIPES-581 or what > is here best practise naming convention?GreetingFlorian > > > Am Mittwoch, dem 24.08.2022 um 19:07 +0000 schrieb Dominik Riemer: > > Hi Florian,happy to help! 1. There is a header in each markdown > > filewith an ID (e.g. in the 01_try-installation.md). This id > > correspondsto the id in the sidebar.json2. Yes, all images are in > > the staticfolder 3. Well, they are not really auto-auto generated > > 😉 There is amaven plugin which extracts the markdown files and > > e.g., createsentries for the sidebar.json and modifies the image > > links so thatthey work on the website, but it's not something > > automated in Githubactions or so, although it would be awesome to > > support this4. Youdon't need to manually add the version, this is > > managed byDocusaurus. The markdown files in the documentation > > folder alwaysrefer to the next unreleased version. When you start > > the website, youcan click on the version (0.69.0 should be the > > default) and thenselect "master" which points you to the unreleased > > version. Aftereach release, we run the "ds-version" command and > > then Docusauruschecks all files in the documentation folder against > > the files fromthe previous release and creates a new docs version. > > E.g., see olderdocumentation files at [1]. In case you want to > > backport changes tothe documentation pages to previous versions, > > these files can also bemodified, but that's rather rare.5. Good > > point, I _think_ this shouldbe possible without any problems, at > > least it's worth a try 😉Hope this helps!CheersDominik[1] > > https://github.com/apache/incubator-streampipes-website/tree/dev/documentation/website/versioned_docs > > > > > > -----Original Message-----From: Florian Micklich < > > [email protected] > > > Sent: Wednesday, August 24, 2022 7:59 PMTo: > > [email protected] > > Subject: Re: [DISCUSS] Documentation - Description for Adapters > > andProcessing ElementsHi,ok, I started docusaurus from source > > Dominik has previouslymentioned and did a build & run website like > > mentioned in theReadme.Next time I am even faster, because I will > > start the "BuildDocumentation" from the documentation/website > > folder, as it itclearly mentioned in the Readme :-D Before I start, > > I am trying tounderstand the structure of this documentation and I > > have somequestions.1.So everything is organised by the > > sidebar.jsonSo the try-installation [1] is linked to the 01_try- > > installation.md file[2]. How is this working if the names does > > not match?2. I see that all images are stored in the static website > > path here[3]. Is this correct?3. Do I understand it correctly that > > all filesin the PE folder [4] are auto generated and will be > > autogenerated next time again? So if I change something here, > > will thisbe overwritten the next time?4.Is it OK if I add the 0.70 > > version inthe version file here [5]?5. Is it OK to structure the > > documents insome more sup-folders? We could discuss the sub-folder > > names here ofcourse but I think that would make the documentation > > little biteasier to navigate for the authors. This includes also > > pictures instep 2.Greetings Florian[1] > > https://github.com/apache/incubator-streampipes-website/blob/dev/documentation/website/sidebars.json#L5[2] > > > > https://github.com/apache/incubator-streampipes-website/blob/dev/documentation/docs/01_try-installation.md[3] > > https://github.com/apache/incubator-streampipes-website/tree/dev/documentation/website/static/img[4] > > https://github.com > > /apache/incubator-streampipes- > > website/tree/dev/documentation/docs/pe[5] > > https://github.com/apache/inc ubator-streampipes- > > website/blob/dev/documentation/website/versions.json > > > > Am Mittwoch, dem 24.08.2022 um 12:32 +0000 schrieb Philipp Zehnder: > > > Hi together,it would be great to have more content in > > > thedocumentation.I am alsoin favor of using docusaurus. It > > > usesmarkdown, which leaves us thepossibility to move to another > > > toolingat some point in the future ifwe want.@Florian please > > > write if yousee something that should be updated orchanged in the > > > currentversion.Cheers,Philipp________________________________Von: > > > DominikRiemer <[email protected]>Gesendet: Mittwoch, > > > August 24,202211:47 AMAn: [email protected] > > > <[email protected]>Betreff: RE: [DISCUSS] Documentation > > > -Description for Adapters andProcessing ElementsHi Florian,Cool! > > > Thedocumentation on the website is based on Docusaurus > > > whichsupportsthings like docs versioning. Docusaurus uses > > > markdown files,so werely on markdown for the documentation.There > > > is a 'website' folderat [1] where you can find the npm scriptsto > > > start docusaurus and a'docs' folder which includes > > > thedocumentation markdown files forthe next release version > > > (selectg"next" in the docs website). Aftera new release, we run a > > > "npm ds-version" which then detects changesin the markdown files > > > and createsa new release docs version.Thedocuments in the "docs" > > > folder can be freely modified andadded.That's a good place where > > > we can add new tutorials. The "pe"foldercontains the > > > documentation of pipeline elements. These arecurrentlygenerated > > > from the StreamPipes source code using thestreampipes-maven- > > > plugin (as some rewriting is needed, e.g., to fixthe paths > > > ofimages). This process is far from perfect and needssome manual > > > work.It would be nice to have some Github actionsscript > > > whichautomatically updates the Documentation, but that's abit > > > moreadvanced task I'd say 😉If you want to make changes to > > > thestructure, this can be done in the"sidebars.json" file [3], > > > whichis 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 AMTo: > > > [email protected] > > > Subject: Re: [DISCUSS] Documentation - Description for > > > AdaptersandProcessing ElementsHello,I would also prefer a short > > > In-Appdocumentation and largerdocumentation "outside" . > > > Personally, Iprefer to read pdf documentsso I can take additional > > > notes. ButHTML is also good for a quickonline search.We must keep > > > in mindwhat kind of documentation we wantto create and should not > > > mixthem. Also, cross-references between theindividual > > > "chapters"should be avoided. This makes it easier ifsomething > > > shouldchange. 1. Quick starter documentation. 2. > > > SetupDocumentation 3.Technical Documentation 4. User > > > manualdocumentation with bestpractiseI think we should hit the > > > road andtake a look along the way :) Iknow the in app > > > documentation is inmarkdown so far?I wouldrecommend to write the > > > documentation inasciidoc [1] [2] This couldbe set up with > > > asciidoctorj [3]. Thismakes it easy to includeeverything in Git > > > and also keep thedocumentation alongside thesource code. So if > > > something isrewritten, the developer can alsochange the > > > documentation. Makesnew screenshots and deletes oldones.3] The > > > creation of a PDF orHTML file can be done with > > > GithubAction. With every commitor with every release. The > > > results can bepushed to the StreamPipeswebsite, I guess?What do > > > youthink?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/asciidoctorjAmMittwoch, > > > dem24.08.2022 um 07:07 +0000 schrieb Dominik Riemer: > > > > Hi,yes, we can do both: In-app documentation which > > > > onlycoverstheconfiguration and a short description of the > > > > adapterandpipelineelement and additional step-by-step > > > > guides/tutorialswithnicescreenshots that are available in the > > > > onlinedocumentation. Wecanhave such step-by-step guides for the > > > > mostfrequently used adapters.@Florian, do you want to work on > > > > such aguide on thewebsite? I knowyou had some really good > > > > documentationideas somewhile ago 😉CheersDominik-----Original > > > > Message-----From: Philipp Zehnder < > > > > [email protected]> Sent:Sunday, August 21, > > > > 20221:07PMTo: [email protected] > > > > Subject: [DISCUSS] Documentation - Description > > > > forAdaptersandProcessing Elements Hi all, here is a new thread > > > > todiscusstheadapter documentation.Here is a link to the > > > > previousdiscussionin therelease thread [1].@Dominik I know that > > > > theregistration isdifferent, but since alladapters already have > > > > thethree files(documentation.md, icon.png, andstring.en), > > > > shouldn’tit bepossible to also display the descriptionin the > > > > UI.How are wedoingcurrently for the icons?Because they are > > > > loaded dynamicallyaswell. I think the maindifference is that > > > > the icons areloadeddirectly from the workercontainer and not > > > > from thebackend.Couldn’t we do it similarly forthe > > > > documentation file?(Pleasecorrect me if I am wrong) > > > > Regardingthe description on theWebsite.I think it would be > > > > great if we couldgenerate this basedon themarkdown files for > > > > each adapter.The documentation.md filesmostlydescribe the > > > > configurationparameters of adapters andprocessors. Ithink it > > > > would be great tohave additional exampleshow to use them.(e.g. > > > > describe how a CSVfile is uploaded or how aPLC isconnected). > > > > Should we include suchexamples intothedocumentation.md file or > > > > should there be anotherlocation forthis?Any thoughts on > > > > that?@Florian you wrote that you would liketo workon the > > > > documentation.If you need anything to start with,please letus > > > > know.Cheers,Philipp[1] > > > > https://lists.apache.org/thread/29w586db1btqo0ps1rgo3fscvt3tvrzg
