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 also > in favor of using docusaurus. It uses markdown, which leaves us the > possibility to move to another tooling at some point in the future if > we want. > @Florian please write if you see something that should be updated or > changed in the current version. > Cheers,Philipp________________________________Von: Dominik Riemer < > [email protected]>Gesendet: Mittwoch, August 24, 2022 > 11:47 AMAn: [email protected] <[email protected]>Be > treff: RE: [DISCUSS] Documentation - Description for Adapters and > Processing Elements > 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 AMTo: > [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/asciidoctorjAm > Mittwoch, dem 24.08.2022 um 07:07 +0000 schrieb Dominik Riemer: > > Hi,yes, we can do both: In-app documentation which only covers > > theconfiguration and a short description of the adapter and > > pipelineelement and additional step-by-step guides/tutorials with > > nicescreenshots that are available in the online documentation. We > > canhave 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 knowyou had some really good documentation ideas some > > while ago 😉CheersDominik > > -----Original Message-----From: Philipp Zehnder < > > [email protected]> Sent: Sunday, August 21, 2022 > > 1:07PMTo: [email protected] > > Subject: [DISCUSS] Documentation - Description for Adapters > > andProcessing Elements Hi all, here is a new thread to discuss > > theadapter documentation.Here is a link to the previous discussion > > in therelease thread [1].@Dominik I know that the registration is > > different, but since alladapters already have the three files > > (documentation.md, icon.png, andstring.en), shouldn’t it be > > possible to also display the descriptionin the UI.How are we doing > > currently for the icons?Because they are loaded dynamically as > > well. I think the maindifference is that the icons are loaded > > directly from the workercontainer and not from the backend. > > Couldn’t we do it similarly forthe documentation file? (Please > > correct me if I am wrong) Regardingthe description on the Website. > > I think it would be great if we couldgenerate this based on the > > markdown files for each adapter.The documentation.md files mostly > > describe the configurationparameters of adapters and processors. I > > think it would be great tohave additional examples how to use them. > > (e.g. describe how a CSVfile is uploaded or how a PLC is > > connected). Should we include suchexamples into the > > documentation.md file or should there be anotherlocation 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
