Closed elBoberido closed 3 years ago
First step of the documentation for the website will be done in #283
IMHO we need to differentiate between three levels: Beginner (non-technical people), intermediate (every developer), advanced (expert/ core developers).
As Markdown is limited when it comes to e.g. including files, I suggest to switch to reStructuredText. Other ideas have been mdBook or MkDocs.
Having the files in one repository has the advantage, that we can update them easily during development. I propose an export via a CI job into the iceoryx-web repository that is then serving iceroyx.io via GitHub pages.
Proposed table of contents for the website and repository is depicted below:
Repository:
Path | Goal | Target audience |
---|---|---|
./README.md |
Brief introduction | Every developer (Beginner/intermediate) |
./doc/goals-non-goals.md |
Provide background about the project | Every developer (Intermediate) |
./doc/design/* |
Store detailed design documents | Core developers (Advanced) |
./doc/website/* |
How to use? | Non-technical people, developers and integrators new to iceoryx |
Website:
Path | Goal | Target audience |
---|---|---|
./doc/website/introduction.md |
Introduction to Eclipse iceoryx | Non-technical people |
./doc/website/getting-started/overview.md |
Introduce modules (RouDi, Runtime, etc.) | Developer (intermediate) |
./doc/website/getting-started/installation.md |
How to build and install? | Developers, Integrators (intermediate) |
./doc/website/getting-started/examples.md |
Walkthrough through the examples and present various use-cases | Developers, Integrators (intermediate) |
./doc/website/for-developers/* |
Advanced, in-depth topics | Expert/core developers |
First step will be implemented in #283
First test worked, index.html
is available: https://eclipse-iceoryx.github.io/iceoryx-web/
Creating and extending the actual content and reworking the e.g. description of the utils (or to whatever it will be renamed) belong to a different issue in my opinion. (It should be mainly for the website structure, at least as long as we still have parts of the content in the repository itself). We are overloading this issue otherwise. @budrus I can create such a 1.0 documentation issue if this is agreed on.
Also it is ice ensemble, as in an ensemble of iceoryx applications running together to demonstrate the complete capabilites of iceoryx (potentially eliminating the need of the multi publisher example, which we can decide on later).
First test worked,
index.html
is available: https://eclipse-iceoryx.github.io/iceoryx-web/ Open points:* [x] Missing forward from iceoryx.io * [ ] Try preferred workflow with doxygen + doxybook2 + MkDocs * [ ] Rework iceoryx_utils readme / safe standard library * [ ] Introduce iceensamble (Show C <-> C++, History-Feature) * [ ] Move iceperf to iceoryx_posh/stresstest/ * [ ] Rework complete doxygen docu
@mossmaurice could you please move the tasks to the issue description. It's easier to find and will also be shown in the overview as x of y
with a progress bar
Brief feature description
It would be great to have a nice website.
Detailed information
To have adequate online presence we should have a website with all the stuff related to iceoryx, e.g. documentation, links to github and other communication channels like gitter.
Have a look at zenoh for inspiration. It's build with the static site generator hugo.
An alternative would be zola. Why? Just one word: Rust ;)
Open points w.r.t website:
[ ] Move iceperf to iceoryx_posh/stresstest/[ ] Rework complete doxygen docuMake codeblocks searchable*_on_c
->*_in_c.
Todo for v2.0 (Moved #743)