Making documentation accessible and maintainable

[arnaudgolfouse]

Hello,

I realized that DOCUMENTATION.md might not be up to date with the rest of the code, and in trying to update it, it became quite evident that a lot of information here is redundant with dijkstra-map-gd's documentation. I don't think this is a great system right now, because:

• We need to keep DOCUMENTATION.md and the crates documentation in sync, which is a bit tedious and error prone
• Users are more likely to see DOCUMENTATION.md first, but it is more likely to be out of date (because it isn't directly tied to the code) !

  ---

  So I wonder what we might do to improve this :

  1. Keep things as it is
     • Pros:
     • We don't have the burden of an additional third-party tool.
     • Cons:
     • See above
  2. Automate the generation of DOCUMENTATION.md in some way. This sounds nice but I have no idea if this is even feasible in a straightforward and maintainable way.
  3. Publish the crates to crates.io (the names dijkstra-map / dijkstra-map-gd are available as far as I can tell)
     • Pros:
     • Documentation would be consistent (only one documentation)
     • This would give us automatic access to an easy-to-link documentation on docs.rs
     • Automatic building of the documentation would be easy
     • The dijkstra-map crate would be easy to use by other people
     • Cons:
     • This might require some work setting up
     • This might not be desirable right now : for example it could mean committing to some backward-compatibility regarding the crate's versions.
  4. Build documentation on a Github wiki. I think that would mean building the documentation for dijkstra-map-gd (using cargo doc), and copy-paste it on the wiki as-is.
     • Pros:
     • We already have github actions setup, so hopefully this will play nice with it.
     • Documentation would be consistent (only one documentation)
     • Cons:
     • We would need to determine how to do this
     • Maybe hard to discover for users ?

       ---

       I also consider here that documenting the Rust code is enough : but this is a gdnative documentation, and maybe we would need to document the bindings it produces in gdscript ? Overall I would say the best would be 3., or maybe 4., as they would allow us to simply link to the documentation in the README.md and carry on without thinking about it. But I wonder what you think about it ?

[SimonasLetukas]

I can only comment from a .NET perspective, but automatically generating API descriptions is definitely the way to go. The only catch here is that the code itself then should be commented with the example inputs and nice descriptions, basically everything that is in DOCUMENTATION.md right now. And it would still be quite a mission to check these descriptions before committing any code, so that the generated descriptions are up to date.

[arnaudgolfouse]

Yeah, that is why I think using DOCUMENTATION.md is not the best idea: I would rather directly use the output of cargo doc in some way, as it is much easier to maintain documentation directly written in the code (dijkstra-map-gd/src/lib.rs in this case).

[MatejSloboda]

Yeah, the documentation is an issue. From user perspective, the documentation should stylistically match Godot's documentation (ie. be in GDScript). That's why we originally opted to write it manually into .md file instead of using cargo doc. Rust documentation will be rather opaque to your average godot user (speaking from experience).

Perhaps we should ask guys over at gdnative rust bindings. This seems more like a general issue for all gdnative rust users, than merely our specific problem.

[arnaudgolfouse]

You're right, it should be as easy to read as possible to Godot users... I don't think there is a canonical way to write / distribute documentation in Godot ? (except for the engine's internal documentation)

I will ask in the gdnative rust bindings repository. I don't know if they will be able to help us, but it would be amazing to have a tool to generate this documentation automatically...

[arnaudgolfouse]

Done, we will see how that goes :)

[arnaudgolfouse]

So they pointed to a way to generate this ourselves... To be honest this seems reasonably feasible, and I would gladly do it. I won't be able to work on it for the next few weeks though.

[astrale-sharp]

Okay multiple thoughts :

• it is not stable as of yet but in godot 4.0 there will be good support for in engine documentation for gdscript as can be seen here, and plans for making this feature possible for gdnative seems to be of some interest as can be seen here. This seems very interesting to me (but we'll have to wait till it actually exists)
• In the meantime, the documentation that is of interest for godot users is in only one file : the interface module, so a script that extract it (automated by gitthub actions) shouldnt be to complicated to write and would be a good compromise for the right now I think.

[arnaudgolfouse]

Folks, it is alive ! 🎉

I made a documentation tool here, and it is now published to crates.io, which means it is ready to be used for this project ! Some adjustments will be necessary to make it work, but you can expect a PR relatively soon 🙂

PS: This is usable in (theoretically) any godot-rust project that exports to gdscript !

[arnaudgolfouse]

Since this is now merged and exported to the asset store, I think it's fair to say this issue was resolved 😃