Documenting how to render samples documentation locally

[egekorkan]

While trying to do a fix for #1822 , I wanted to render my local changes in the same way they would be rendered at https://eclipse-dataspaceconnector.github.io/docs/#/submodule/Connector/samples/02-health-endpoint/ . However, I am not able to find how I can do this. I open the index.html in live server (in vs code) but I cannot progress any further since the links on the cover page are absolute (pointing to the GitHub page).

Then, I have dug in and saw that you are using docsify. After installing it, I ran docsify serve docs I still could not access the samples directory using the file paths that are documented at https://docsify.js.org/#/more-pages but then I have realised that samples are not under docs folder so it makes sense that this command does not work.

Then I have tried to change the path to samples but it did not work until I did docsify init in that folder which created two files that should not be created since they are on upstream. At least this way I can see that what I am doing is wrong or not but some explanations on how to render these pages locally would be much appreciated. I am guessing that there is some file manipulation happening for production since the path for the samples is somehow docs/#/submodule/Connector/samples/02-health-endpoint/ (copy pasting this locally does not work)

@juliapampus might be the right person to tag?

[mspiekermann]

@egekorkan https://github.com/eclipse-dataspaceconnector/docs should be the place to find information for the rendering process, since it is used to render the output you see at https://eclipse-dataspaceconnector.github.io/docs/. It was moved to a separate repository to allow consolidating the generation with docsify over the different components.

[juliapampus]

@egekorkan As @mspiekermann already mentioned, you have to checkout the documentation repository. The GitHub pages are built from there. You can use docsify serve docs to deploy the pages locally (from the root folder). If you enter the docs folder, the command is docsify serve.

[egekorkan]

I have understood that but I think some improvement is still needed:

• Nowhere (other than this discussion) is mentioned that one should look there.
• the docs repo is not documenting what is mentioned here

[mspiekermann]

I agree that there are things that need to be improved, if only because the restructuring and working with the cross-repository is something that we introduced just a few days ago. So your feedback is greatly appreciated and support more than welcome!

[egekorkan]

I can provide a README.md or CONTRIBUTING.md at the https://github.com/eclipse-dataspaceconnector/DataSpaceConnector/tree/main/docs level . Would the readme there be picked up by docsify? Regarding contributing.md, eclipse has some restrictions on it if it is on the root level but I guess here it should be fine and people would generally look for something like that. I would simply put that we use docsify and that one can look at the actual docs repository. If one wants to render only a specific repo documentation, they can do docsify init but not commit the generated files.

Would this be fine?

[juliapampus]

Both folders already have a README. Maybe you can add a section about a local deployment in the one at root (via a PR)? This content will not end up in the rendered page, as Docsify only picks up the files in a specific /docs folder. Regarding the CONTRIBUTING.md we are intentionally referring to the one in the Connector Repo as we do not want to maintain duplicate content.

[juliapampus]

If one wants to render only a specific repo documentation, they can do docsify init but not commit the generated files.

Why would someone want to render content as Docsify? Just executing this init command does not add any content to the resulting index.html.