Adding Examples/A Project Skeleton

[HpLightcorner]

To further lower the entry-bar for new CMake users, we should add examples and extend the documentation. A simple project skeleton would also be a good idea.

Furthermore, we could create ready-made CMake Files for common tasks like building INET.

[riebl]

Yes, I absolutely agree. Furthermore, I would like to add such a project skeleton to our tests so we can be sure our proposal is always working ;-)

[riebl]

Please have a look at the feature/basic-example branch @HpLightcorner. Do you think this example is still basic enough?

[thor]

@riebl that's great! (Pardon my butting-in.) I quite like the addition of the opp_add_test, although I'm not sure it's basic-basic, I think it might be easier to get started with than the README. 👍

[riebl]

No need to excuse, your feedback is much-appreciated @thor. The README is currently also our only source where the macros and their arguments are discussed. I would like to have some generated documentation that extracts snippets from our sources. AFAIK, CMake itself relies on Sphinx to produce its (excellent) documentation website. Has anyone thoughts on this topic?

[thor]

That's nice to hear, @riebl. If so, I'll butt-in a bit more. 😉

Has anyone thoughts on this topic?

I haven't touched on generating documentation for CMake packages, but I've certainly spent more time than I thought I would on documentation generation in general.

Judging by #10, I think that seems quite nice. The easier you can tie in the documentation to the code it self (for APIs, etc.), usually the better. I'm quite partial to AsciiDoc over rST, but with the support that comes with Sphinx due to CMake itself using it, it seems like a much easier choice. It's tricker if we were to contemplate which general documentation generator to use if the content was not as tightly integrated with the source itself.

Sphinx seems like a good choice in that sense.

[HpLightcorner]

Adding both, the documentation and the examples will give the user the most straightforward way to use the package. I am heavily using Doxygen for the docs of my simulations and packages, so Sphinx seems to be similar, and I totally agree with @thor - the closer code and documentation go, the better. However, I never used Sphinx before, so also a good time to learn something new (thanks, @riebl for #10).

Regarding feature/basic-example - from my perspective, that's an excellent starting point - especially as this closely aligns with the OMNeT++ examples.

Shall we add scripts for adding INET also into the examples folder, or is there a better place for that? E.g. adding a common folder or a modules folder where those scripts live, the developer can add them as needed, like calling a function? I mean, INET is, at the moment, the most obvious package which the users will need very often.