Expose documentation tool for godot rust projects

[astrale-sharp]

Hi there, i have found a very interesting tool that i think we should mention in the book.
gdnative-doc parses the documentation in the rust code and generate the documentation in markdown (that can be shipped with an addon you're developping for instance)
It can also take your doc test in ```gdscript and put them into a test_file so they can be run by Gut.
Its also flawlessly integrated into cargo

It is used in a project i contributed to

It would be pertinent to look at

1. the build.rs file
2. the structure exported to godot
3. the generated doc
4. the generated Test

This could all be part of a section about developping addons in godot-rust for instance (which i would be interested in writing) what do you think?

[astrale-sharp]

by the way, it make me think it could be used to implement an automatic test from godot features using this and the command line of the Gut addon, just an idea

[Bromeon]

Generally sounds like a good idea -- there are some other integrations worth mentioning in the future, e.g. godot-egui.

However, there are some caveats:

• Some tools are very specialized for the author's use case, and open-sourced so that others could potentially use it, but not to build a library/tool as primary goal.
• Early prototype of tools tend to change a lot. If we add examples, they may quickly become outdated. I expect that tool authors are not actively updating the godot-rust book to reflect their changes all the time. And I don't see the godot-rust team chasing external APIs, either.

So maybe it makes sense to have a section Third-party integrations (maybe after 9. Advanced Guides). This section mentions tools, libraries and other integrations, contains 2-3 high-level sentences about the purpose as well as a link, but does not have code or other examples. It is then the responsibility of said integrations to provide a motivating, up-to-date description on their main page (website or GitHub repo).

Even then, there would still need to be some basic curation; projects that haven't been updated in a while could be removed, dead links would need to be updated, etc.

I am also thinking we could do something similar for games built with godot-rust.

What do you and others think?

[astrale-sharp]

I think it makes a lot of sense to put this and the like in a Third-party integrations and also to have games made in godot rust somewhere Made with godot-rust

I'd be interested to open a PR on the subject

[Bromeon]

Glad to hear that! Maybe let's wait for some more input before rushing to implementation 🙂

[jacobsky]

I mentioned this in the discord, but I'm all for a "Third Party Integrations" section, so long as we very explicitly mention that these are "as-is" and that they are intended to act as a starting point, not necessarily as anything that we explicitly support. If we go this route.

[astrale-sharp]

Yes ofc! I'm just showing my enthusiasm !
A little list of the task at hands that I will keep updated here to keep things organized :

• Modify src/SUMMARY.gd : add a third Item (Third-party integrations) to Advanced Guides
• Write a little summary/ explanation of the goal of this new part of the book in third_party_integrations.md
• List some third-party integrations mentioned on discord or elsewhere namely :
• gdnative-doc ? (mentioned upper)
• godotEgui (mentioned below)
• project-utils (mentioned below)

Please ping me (or maybe open an issue) if you know of more third-party integrations that should be included.
This is just a proposition, if you think something should be changed, let's discuss it!

[jacobsky]

@astrale-sharp That plan looks good to me for now. Third-party integrations can be in either Advanced Guides or as it's own sections. I don't think we need to worry about it too much at the moment.

A third party integration that I am working with another member of the community is GodotEgui and while there's a fair bit of documentation on the github repo's readme, if you are interested in creating a section we'd always appreciate it. Otherwise, I might take a day to add the section as well.

One project that got a little delayed was the project-utils which is a bit old, but could be useful to have a guide for configuring it.
For my part, I'm in the process of creating an Addon that can help to integrate it all a bit better into Godot.

[astrale-sharp]

Taken into account by editing the previous comment !

I'd be happy to write a section about GodotEgui.

I was of the opinion of @Bromeon that the tutorial part should be the responsibility of the others projects. What do you think?

[Bromeon]

We are adding the empty pages for third-party projects in godot-rust/book#46.
As soon as it's merged, you are welcome to add some content!

godot-egui would fit into the Tools and Integrations part. You are right, we should leave the tutorial up to the other projects. Maybe just write 2-3 high-level sentences what the project is about, and if possible add a screenshot 🙂

Could you reuse #49 for this, so we don't have dozens of empty PRs?
(or #47 if you want me to re-open it)

[jacobsky]

I agree with the sentiment that tutorials are best left to the recipes section or the relevant projects. As long as we provide a link to the main repository most users should be able to find the relevant docs.