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.json 2. 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 this 4. 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! Cheers Dominik [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 PM To: [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 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
