When linking to example documentations throughout the documentation it is not possible to have working links on the examples.
Either the links are invalid on github or the website
We use github URLs which have the big disadvantage that they have to be adapted for every tag/branch for every release. Which is error prone and in the past we overlooked more then one link.
We use website URLs which have the disadvantage that they cannot be reviewed in a pull request since it is possible that they link to something which will vanish with the PR or newly introduced.
Furthermore URLs have the disadvantage that they lead to context switches in a sense that the user is switching from website to github back and forth.
Possible solution
Move the few documents which are only intended for the website into the website repository. This would effect only the index.md all the other documents are also relevant for github.
If the folder structure of the website and the iceoryx repository would be identical we would have much less trouble with relative links
Shell script which copies the required markdown documents and the correct position and adjusts links when the website is deployed. This script should be part of the website repo.
Other considerations
Not everything on the website should be versioned.
FAQ
start page
?advanced?
what is eclipse iceoryx
The reason is that those documents are interesting for every reader and the content should be independent of the iceoryx version.
Tasks
General:
[ ] replace all the README.md links in iceoryx_examples with absolute links to github 'tree/main'
[ ] check which README.md links in 'doc' need to be adjusted as well
all relative links in 'doc' might be broken
For release script:
[ ] replace all 'tree/*/' with 'tree/release-branch/' -> #1197
[ ] check for all release notes in 'doc/website/release-notes/' have an entry in the corresponding '.pages'
[ ] check for all examples in 'doc/website/release-notes/' have an entry the corresponding '.pages'
For website script:
[ ] replace all > [NOTE] with !!! note, etc.
[ ] replace https://github.com/eclipse-iceoryx/iceoryx/iceoryx_examples/ with links to website examples
[ ] replace https://github.com/eclipse-iceoryx/iceoryx/doc/ with links to website pages
[ ] replace <!--[Check out ... { .md-button }--> with [Check out ... { .md-button }
elfenpiff
commented
2 years ago
Required information
When linking to example documentations throughout the documentation it is not possible to have working links on the examples.
Furthermore URLs have the disadvantage that they lead to context switches in a sense that the user is switching from website to github back and forth.
Possible solution
index.mdall the other documents are also relevant for github.Other considerations
Not everything on the website should be versioned.
The reason is that those documents are interesting for every reader and the content should be independent of the iceoryx version.
Tasks
General:
For release script:
For website script:
> [NOTE]with!!! note, etc.https://github.com/eclipse-iceoryx/iceoryx/iceoryx_examples/with links to website exampleshttps://github.com/eclipse-iceoryx/iceoryx/doc/with links to website pages<!--[Check out ... { .md-button }-->with[Check out ... { .md-button }