Open Ayush1325 opened 2 years ago
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?
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.rsShould 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:
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.
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.
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.
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
Yeah, mdbook makes sense
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.
We need to have a mdBook that makes getting started with qmetaobject easier.
Goals:
Optional Goals:
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.