Create a mdBook for qmetaobject

[Ayush1325]

We need to have a mdBook that makes getting started with qmetaobject easier.

Goals:

• [ ] Steps to setup development for all platforms supported by qmetaobject
• [ ] Beginner-friendly application walkthrough
• [ ] Tutorials about doing some commonly required stuff in qmetobject.
• [ ] Tutorial for Adding Rust wrappers for Qt C++ API (Already present in Readme)
• [ ] Getting Help section (maybe a matrix or zulip room)
• [ ] Getting Involved section

Optional Goals:

• [ ] An advanced section containing information about using async Rust with qmetaobject
• [ ] Information about inner workings of qmetaobject

This should also help in cleaning up and updating the examples present in qmetaobject and attracting new people and contributors. Currently, the lack of documentation makes it feel not ready for serious projects.

[ogoffart]

Sounds good. I could enable the wiki.

But I believe the best would be to have markdown files in a docs/ folder in the repository. They could also be added in a #[cfg(doc)] mod docs modules or so, so it is shown in docs.rs

Should I enable the wiki in this repository?

[Ayush1325]

Sounds good. I could enable the wiki.

But I believe the best would be to have markdown files in a docs/ folder in the repository. They could also be added in a #[cfg(doc)] mod docs modules or so, so it is shown in docs.rs

Should I enable the wiki in this repository?

I am not well versed in how this should be done either. The options I know about are the following:

1. Github Wiki: Seems to be used pretty less for some reason. Not a bad option but might not be best, especially for discoverability.
2. Github Pages: Used by serde and many other rust crates. Seems a little more work than wiki to get started but a lot more flexible and discoverable.

As far as showing it in docs.rs, I don't think that is necessary. I mainly want the things that cannot be present in the docs.rs to be show in the manual. Things like tutorials and walkthroughs. Adding them to docs.rs might generate more noise in docs than helping.

The main thing I want to tackle is to improve awareness about this project. Currently, most people don't really know about it's existence and state. After messing around with the source code in the past few months, I have found a lot of things that I didn't even consider to be possible when I initially started contributing. Having manual should help bring in newbies.

[ogoffart]

I think having the .md files in a folder in git is exactly like a wiki. The github web interface renders them properly, and they can be edited from there too. The advantage of the .md files is that they are part of the git history and versioned with the rest of the project.

[Ayush1325]

I think having the .md files in a folder in git is exactly like a wiki. The github web interface renders them properly, and they can be edited from there too. The advantage of the .md files is that they are part of the git history and versioned with the rest of the project.

Hmm. Do you think they will show up on search results though? It would be great if the manual could be discovered without needing prerequisite knowledge about the existence of this project. For example, on searching for serde, the first result I get is Overview Serde.

[ogoffart]

It seems that neither wiki, nor file in repository other than the readme, are indexed by google. So i guess the easier would be to add them to docs.rs (they can be included with #[doc = include_str!("docs/foobar")] pub mod foobar {} ) because docs.rs is indexed

[Ayush1325]

@ogoffart How about using something like GitBook or mdBook? I think we can use mdBook + Github Pages in a docs folder.

[ogoffart]

Yeah, mdbook makes sense

[Ayush1325]

Yeah, mdbook makes sense

Ok, there is also a Github Action for mdbook which just needs the mdbook stuff to be present under a folder so it should be pretty similar to just having md files in the docs folder in terms of maintenance.