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 PM To: [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 file > with an ID (e.g. in the 01_try-installation.md). This id corresponds > to the id in the sidebar.json2. Yes, all images are in the static > folder 3. Well, they are not really auto-auto generated 😉 There is a > maven plugin which extracts the markdown files and e.g., creates > entries for the sidebar.json and modifies the image links so that > they work on the website, but it's not something automated in Github > actions or so, although it would be awesome to support this4. You > don't need to manually add the version, this is managed by > Docusaurus. The markdown files in the documentation folder always > refer to the next unreleased version. When you start the website, you > can click on the version (0.69.0 should be the default) and then > select "master" which points you to the unreleased version. After > each release, we run the "ds-version" command and then Docusaurus > checks all files in the documentation folder against the files from > the previous release and creates a new docs version. E.g., see older > documentation files at [1]. In case you want to backport changes to > the documentation pages to previous versions, these files can also be > modified, but that's rather rare.5. Good point, I _think_ this should > be 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 and > Processing Elements > Hi,ok, I started docusaurus from source Dominik has previously > mentioned and did a build & run website like mentioned in the > Readme.Next time I am even faster, because I will start the "Build > Documentation" from the documentation/website folder, as it it > clearly mentioned in the Readme :-D Before I start, I am trying to > understand the structure of this documentation and I have some > questions.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 files > in the PE folder [4] are auto generated and will be auto > generated next time again? So if I change something here, will this > be overwritten the next time?4.Is it OK if I add the 0.70 version in > the version file here [5]?5. Is it OK to structure the documents in > some more sup-folders? We could discuss the sub-folder names here of > course but I think that would make the documentation little bit > easier to navigate for the authors. This includes also pictures in > step 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 the > > documentation.I am alsoin favor of using docusaurus. It uses > > markdown, which leaves us thepossibility to move to another tooling > > at some point in the future ifwe want.@Florian please write if you > > see something that should be updated orchanged in the current > > version.Cheers,Philipp________________________________Von: Dominik > > Riemer <[email protected]>Gesendet: Mittwoch, August 24, > > 202211:47 AMAn: [email protected] < > > [email protected]>Betreff: RE: [DISCUSS] Documentation - > > Description for Adapters andProcessing ElementsHi Florian,Cool! The > > documentation on the website is based on Docusaurus whichsupports > > 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 scriptsto start docusaurus and a > > 'docs' folder which includes thedocumentation 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 createsa 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" > > foldercontains the documentation of pipeline elements. These are > > currentlygenerated from the StreamPipes source code using the > > streampipes-maven-plugin (as some rewriting is needed, e.g., to fix > > the paths ofimages). This process is far from perfect and needs > > some manual work.It would be nice to have some Github actions > > script whichautomatically updates the Documentation, but that's a > > bit moreadvanced 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 AMTo: > > [email protected] > > Subject: Re: [DISCUSS] Documentation - Description for Adapters > > andProcessing ElementsHello,I would also prefer a short In-App > > documentation and largerdocumentation "outside" . Personally, I > > prefer to read pdf documentsso I can take additional notes. But > > HTML is also good for a quickonline search.We must keep in mind > > what kind of documentation we wantto create and should not mix > > them. Also, cross-references between theindividual "chapters" > > should be avoided. This makes it easier ifsomething should > > change. 1. Quick starter documentation. 2. Setup > > Documentation 3.Technical Documentation 4. User manual > > documentation with bestpractiseI think we should hit the road and > > take a look along the way :) Iknow the in app documentation is in > > markdown so far?I wouldrecommend to write the documentation in > > asciidoc [1] [2] This couldbe set up with asciidoctorj [3]. This > > makes it easy to includeeverything in Git and also keep the > > documentation alongside thesource code. So if something is > > rewritten, the developer can alsochange the documentation. Makes > > new screenshots and deletes oldones.3] The creation of a PDF or > > HTML file can be done with GithubAction. With every commit > > or with every release. The results can bepushed to the StreamPipes > > website, 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, dem > > 24.08.2022 um 07:07 +0000 schrieb Dominik Riemer: > > > Hi,yes, we can do both: In-app documentation which only > > > coverstheconfiguration and a short description of the adapter > > > andpipelineelement and additional step-by-step guides/tutorials > > > withnicescreenshots that are available in the online > > > documentation. Wecanhave such step-by-step guides for the most > > > frequently used adapters.@Florian, do you want to work on such a > > > guide on thewebsite? I knowyou had some really good documentation > > > ideas somewhile ago 😉CheersDominik-----Original Message----- > > > From: Philipp Zehnder <[email protected]> Sent: > > > Sunday, August 21, 20221:07PMTo: [email protected] > > > Subject: [DISCUSS] Documentation - Description for > > > AdaptersandProcessing Elements Hi all, here is a new thread to > > > discusstheadapter documentation.Here is a link to the previous > > > discussionin therelease thread [1].@Dominik I know that the > > > registration isdifferent, but since alladapters already have the > > > three files(documentation.md, icon.png, andstring.en), shouldn’t > > > it bepossible to also display the descriptionin the UI.How are we > > > doingcurrently for the icons?Because they are loaded dynamically > > > aswell. I think the maindifference is that the icons are > > > loadeddirectly from the workercontainer and not from the > > > backend.Couldn’t we do it similarly forthe documentation file? > > > (Pleasecorrect me if I am wrong) Regardingthe description on the > > > Website.I think it would be great if we couldgenerate this based > > > on themarkdown files for each adapter.The documentation.md files > > > mostlydescribe the configurationparameters of adapters and > > > processors. Ithink it would be great tohave additional examples > > > how to use them.(e.g. describe how a CSVfile is uploaded or how a > > > PLC isconnected). Should we include suchexamples into > > > thedocumentation.md file or should there be anotherlocation for > > > this?Any thoughts on that?@Florian you wrote that you would like > > > to workon the documentation.If you need anything to start with, > > > please letus know.Cheers,Philipp > > > [1] > > > https://lists.apache.org/thread/29w586db1btqo0ps1rgo3fscvt3tvrzg
