Prototype an md-book version of the crate

Question

Prototype an md-book version of the crate

Opened this issue a year ago · 7 comments

Prototype a md-book version of the same crate. It should use docify-cli.

Answer 1 · 2023-11-10T15:07:29.000Z

@sam0x17 is this something you can help us with?

Answer 2 · 2023-11-10T16:08:50.000Z

Yeah the idea here would be giving docify the ability to output an mdbook similar to how it can already compile markdown files. Once I am done with the other features that I am finishing up, this could be a good next target

I have never worked with generating mdbooks directly so if they are all defined in markdown then this honestly will already just work with docify's markdown directory compiling feature, so it could be quite easy

Answer 3 · 2023-11-15T10:27:57.000Z

Adding some context sam0x17/docify#23

Answer 4 · 2024-01-08T22:56:25.000Z

I am interested in the motivation for this issue: what does mdBook provide that RustDocs does not exactly? As I read it, in the context mentioned in docify#23 , perhaps exposing (almost) the same information as Rustdocs is desired... Why?

Perhaps the motivation is to have a higher level book that exposes https://github.com/paritytech/polkadot-sdk/tree/master/docs in a more typical end user docs site than pure rust docs is?

If there is a more full writeup somewhere of the motivation/goals, please LMK 🙏

For ref, I have some experience with mdBook in crafting https://github.com/Polkadot-Blockchain-Academy/pba-book so hope the learning from that work could help, and perhaps even be combined into some main Book for the SDK that included or exposed/linked PBA materials as I think they are quite useful for end users WRT concepts mostly.

Answer 5 · 2024-01-10T16:07:51.000Z

Yeah my understanding is it is mostly embedding/CSS motivated

Answer 6 · 2024-01-31T21:50:55.000Z

I have been considering sam0x17/docify#23 and researching what feels best in DevEx for those writing docs & source. To me, use of mdBook's plugins with pure markdown and example code (that supports testing against source vs. a rust file with heavy doc comments would be cleaner and easier to use tooling/IDES for. (see also paritytech/polkadot-sdk#2991 that is a bit of a hybrid for split files, with the nice feature that rs files can use LSPs, where md example blocks afaik cannot).

It might to me to be possible to use docify to tightly couple rust docs build, so you can develop and test examples with a "pure" mdBook (with option to do hybrid, as mentioned). The missing link 😉 is called out in the issue mentioned though... Handling [`Trait`] links in mdBook... I think this could be handled by some mdbook plugin and cargo hooks / a build.rs file. I have been experimenting towards that end but nothing to show just yet. I am not sure, but it may be possible to inject the book in full into rustdocs so it lives on docs.rs for SEO, if not, using docify to build them in rustdocs direct should work as it does in that hybrid example.

WDYT about a push towards a "real" mdBook that is tightly coupled with cargo to get the testing, building, and linking working?

Answer 7 · 2024-01-31T22:34:08.000Z

Handling [`Trait`] links in mdBook... I think this could be handled by some mdbook plugin and cargo hooks / a build.rs file.

Yeah you hit the nail on the head here, my whole reason for advocating a rustdocs-based approach is the built in handling for these things which are actually quite non-trivial when you have re-exports of re-exports of re-exports coming into play in module resolution.