Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a gdextension online documentation guide. #9966

Open
wants to merge 9 commits into
base: master
Choose a base branch
from

Conversation

Ivorforce
Copy link
Contributor

First step to address godotengine/godot-proposals#10733.

The guide explains, in very short, how to create online documentation (much like the godot docs themselves) for a gdextension.

You can see a working example here: https://numdot.readthedocs.io/ (source).

A link to my example might be helpful to recreate what I did - but I elected not to link it because I felt it may be weird to link to a third party project. Let me know what you think.

@AThousandShips AThousandShips requested a review from a team September 16, 2024 17:58
@AThousandShips AThousandShips added enhancement area:manual Issues and PRs related to the Manual/Tutorials section of the documentation topic:gdextension labels Sep 16, 2024
Copy link
Contributor

@paddy-exe paddy-exe left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good so far. Some parts could be phrased differently to make it clearer how to set it up though. Thanks for contributing to the docs 🙌🏻

Comment on lines 193 to 194
This is where you'll have to get a bit creative, but here's a rough outline
of the steps involved:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should be phrased differently. Many of the people reading the docs will try to mimic the instructions even with a different setup so this should be phrased that the setup should be identical so the steps work. Otherwise we will get open issues complaining that the steps don't work.

Copy link
Contributor Author

@Ivorforce Ivorforce Sep 19, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm trying to convey that the steps are very 'unprecise' with this sentence, because I needed to use a good amount of insight (while editing those 3 files) beyond this simple plan to actually get it to run. Describing all of the steps here would result in a pretty large and probably unhelpful and soon to be outdated tutorial.

The only assumption the text is making is that the documentation files are in doc_classes (ensured by doctool). It should really work with any kind of setup beyond that.

I'm not sure how to phrase it differently to convey this better, got any suggestions?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Ivorforce Perhaps along the lines of:

The setup may differ depending on how your project is structured. Here are the exemplary steps you would need to take to compile the documentation into rst files.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think i see where you're coming from, but the following steps actually do not depend on the project structure at all. This is just a guideline for how to adapt the Godot docs with different content. It's basically independent of the project itself, at least after the XML Generation step.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have edited the section with a new phrasing. Hopefully this conveys it better?

@Ivorforce
Copy link
Contributor Author

Forgot that I also needed version.py. i added that bit in.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area:manual Issues and PRs related to the Manual/Tutorials section of the documentation cherrypick:4.3 enhancement topic:gdextension
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants