Replacement for shortcode docs links

[alice-i-cecile]

Problem definition

1. Short codes are error-prone to write, with a huge number of matching delimiters.
2. Short codes are very hard to read, due to their verbose syntax, arbitrary ordering and lack of support on Github and in IDEs. e.g. {rust_type(type="struct" crate="bevy" mod = "ecs/system" name="EntityCommands" no_mod = "true")}}.
3. Short codes are a strange DSL that new contributors to the book must memorize.
4. Short codes force authors to look up the fully qualified path each type.
5. Short codes require authors to explicitly state whether a given import is a struct, enum, trait or so on.

Requirements

1. Human-legible form is easy to write and read.
2. Acceptable level: struct{{bevy::ecs::system::EntityCommands}}
3. Machine-legible form is standard zola-compatible HTML that links to the appropriate docs.rs page.
4. Docs links must support custom formatting.
5. Human-legible form is committed and reviewed.

Bonus points

1. Hot reloading still works.
2. Implicit imports: automatically assume Bevy prelude: struct{{EntityCommands}}
3. Type elision: {{bevy::ecs::system::EntityCommands}}
4. Explicit imports: list use bevy::ecs::system::EntityCommands at the top of the file, which is processed out, allowing the author to write struct{{EntityCommands}}.

Possible strategies

1. Fork Zola to add support for this.
   1. Probably more immediately elegant.
   2. Significantly more maintenance burden unless merged upstream.
   3. Should only involve writing our own tera functions.
   4. Best we can do is likely {{rs(name="App"}} due to tera limitations :(
   5. Difficulties integrating with our CI.
2. Add a Rust preprocessor which modifies the .md files provided.
   1. These are stored in the build directory and are not commited.
   2. Begin with simple instructions to run the preprocessor before zola serve.
   3. Eventually, wrap this in its own minimal CLI to support hot reloading and one-command builds.
3. Use reference style links instead of short-codes.
   1. Works out of the box!
   2. Very legible.
   3. No special formatting out of the box. Can this be added?
   4. Requires looking up the full URL, and modifying it to either use latest or doing a find-and-replace each Bevy version.

[alice-i-cecile]

Reference style links are extremely ergonomic:

The [`App`] is the beginning and end of Bevy: the Alpha and Omega.

[`App`]: https://docs.rs/bevy/0.5.0/bevy/app/struct.App.html

Before:

The {{rust_type(type="struct" crate="bevy" mod = "ecs::query" name="Access" no_mod=true)}} struct returned by those methods keeps track of the read and write accesses of a system: either on a {{rust_type(type="trait" crate="bevy" mod = "ecs::component" name="ComponentId" no_mod=true)}} or {{rust_type(type="trait" crate="bevy" mod = "ecs::archetype" name="ArchetypeComponentId" no_mod=true)}}.
These store the types of each resource and component as a cheap, safe identifier ultimately created out of a {{rust_type(type="struct" crate="std" mod = "any" name="TypeId")}} during type registration, which automatically occurs the first time a component or resource type is used.
This, fundamentally, is why we're limited to one of each type of component per entity: we use this type information to dispatch data.

After:

The [`Access`] struct returned by those methods keeps track of the read and write accesses of a system: either on a [`ComponentId`] or [`ArchetypeComponentId`].
These store the types of each resource and component as a cheap, safe identifier ultimately created out of a [`TypeId`] during type registration, which automatically occurs the first time a component or resource type is used.
This, fundamentally, is why we're limited to one of each type of component per entity: we use this type information to dispatch data.

[`Access`]: https://docs.rs/bevy/0.5.0/bevy/ecs/query/struct.Access.html
[`ComponentId`]: https://docs.rs/bevy/0.5.0/bevy/ecs/component/struct.ComponentId.html
[`ArchetypeComponentId`]: https://docs.rs/bevy/0.5.0/bevy/ecs/archetype/struct.ArchetypeComponentId.html
[`TypeId`]: https://doc.rust-lang.org/stable/std/any/struct.TypeId.html

[Weibye]

As someone not familiar with the subject: What are the benefits of short-codes in the first place?

[cart]

• They integrate directly with Zola, which means the developer experience is as simple as running zola serve. It will listen for changes to files and immediately rebuild pages as they change.
• They are simple to insert into the existing Zola markdown pipeline. Just small snippets of Tera templates, so they fit in right alongside the other templates in our Zola site.
• They can insert arbitrary html, so we get nice custom formatting for "rust symbols"
• Structured: accepts typed inputs

[mockersf]

Zola has a load_data function that can be used in shortcode. Would it be possible to call the RLS in an http api call to get the data we need?

[killercup]

I think the ref links are quite a good way. You can still use short codes to make updating the links to a newer version easy.

---

But I have also have another idea that's a bit weird: Write the book in rustdoc!

Basically, you get

• links to the right version of bevy
• and testable rust code blocks

at the cost of

• limited design
• and a weird way to publish it.

[alice-i-cecile]

But I have also have another idea that's a bit weird: Write the book in rustdoc!

Yeah, it's appealing, but the marketing value of a coherent, pretty look is too high :p See #143 for more discussion on this point, particularly from Cart.