providing examples for each CellType

[JHenneberg]

As promised in #17 I want to provide a few CellType examples. There are different options. The examples can live in the README.md as already started or a dedicated example folder could be created or actually both could be in sync.

I like the idea of having executable examples and simultaniously the same in the README.md. This of course means manually syncing of both because for now Markdown can not include any source code from a file automatically but those examples are probably not changed very often. Also some people might think the README.md is to bloaded then.

[Andlon]

My personal opinion is that the README might contain one or two motivating examples, but further examples should rather reside in a dedicated location. The examples folder is a pretty solid place for this, I believe. Although one can also make the case for including examples in doc tests. In fact, you could do both: I think you could do (just sketching out)

#[doc = include_str!("../examples/hex.rs")]
mod examples {}

whether or not this is a good idea, I don't know, but thought I'd throw it out there.

[elrnv]

I second that we should keep the readme concise, with a few select (definitely non-exhaustive) examples for how to use this lib (e.g. import/export examples, and how to build meshes). We can simply link to the examples directory (or a readme there that will summarize the what examples we have).

I am not opposed to including the examples in docs. This way folks can get most of the usage info without leaving docs.rs, and most importantly without digging through the code. However I think I would prefer a dedicated module solely for documenting these examples to which we can link from lib.rs.

I suspect many of the cell types can be grouped together into a single example.

[JHenneberg]

I am not opposed to including the examples in docs. This way folks can get most of the usage info without leaving docs.rs, and most importantly without digging through the code. However I think I would prefer a dedicated module solely for documenting these examples to which we can link from lib.rs.

Coud you elaborate this more in detail? You are not talking about rustdoc, no or yes?

My personal opinion is that the README might contain one or two motivating examples, but further examples should rather reside in a dedicated location. The examples folder is a pretty solid place for this, I believe. Although one can also make the case for including examples in doc tests. In fact, you could do both: I think you could do (just sketching out)

#[doc = include_str!("../examples/hex.rs")]
mod examples {}

whether or not this is a good idea, I don't know, but thought I'd throw it out there.

Have a look at #19 . So you mean in vertex.rs should be addional a doctest example?

[elrnv]

Coud you elaborate this more in detail? You are not talking about rustdoc, no or yes?

Yes exactly! I'm referring to rustdoc, which can be generated with cargo doc, which is served by docs.rs for free for all published crates on crates.io.

Have a look at #19 . So you mean in vertex.rs should be addional a doctest example?

I'd love to have @Andlon weigh in on this, but my preference is to keep the "examples" directory for complete use-case type of examples. For instance an example of how one might use vtkio to do something specific like load a vtk file, change it or render it with a third party library, or simply create a vtk file of a complex mesh for some purpose. I expect the examples for building all the different kinds of cell types to be short, so I would just put in an examples module like you did, but just use //! in examples/mod.rs and add a short description for each cell type.

Adding the example code as

#[doc = include_str!("../examples/hex.rs")]
mod examples {}

will not be formatted correctly as code and will be missing the ability to add formatted descriptions around the examples, so I would suggest to avoid that method altogether.

These are just suggestions, I would be happy to accept a PR with examples in whatever format you think is most appropriate so long as they are clear and concise.