-
-
Notifications
You must be signed in to change notification settings - Fork 3.5k
Simplify the "Adding documentation" article for godot-cpp, and de-duplicate format information. #11319
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
base: master
Are you sure you want to change the base?
Simplify the "Adding documentation" article for godot-cpp, and de-duplicate format information. #11319
Conversation
9636557
to
4c70c98
Compare
…licate information.
4c70c98
to
882e2d8
Compare
constants, signals, and more. | ||
|
||
.. note:: | ||
To get started, identify your project's ``demo`` folder, which should contain a Godot project with your extension |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think in this case we should just say "identify your project's demonstration or testing project folder" since otherwise I see some people being confused that they need a demo folder
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How about "identify your project's test project folder"?
|
||
.. image:: img/gdextension_docs_generation.webp | ||
|
||
Documentation styling |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This should not be deleted as there is an overlap with the general RichText documentation but not every tag works in the GDExtension documentation. I tested every tag and wrote down each one that works.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I added a link to Class reference primer, which is what these files are. It is unrelated to the RichtText
format (although there is some overlap).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I see. There's no img
or color
support in the class reference primer though as I see but are supported by the GDExtension docs system though.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Perhaps the documentations are just missing this piece of information?
Since I think it's using the same system, I'd be surprised if there were features in GDExtension docs that aren't supported by Godot's class reference.
`godot-docs <https://github.com/godotengine/godot-docs>`_ uses `Sphinx <https://www.sphinx-doc.org/en/master/>`_. | ||
You can use the repository as a basis to build your own documentation system. | ||
The following guide describes the basic steps, but they are not exhaustive: | ||
You will need a bit of personal insight to make it work. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What is meant here by personal insight
? That seems unclear
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The idea was to communicate that the tutorial is not "complete", and whoever wants to publish their documentation will need to put in additional work beyond what the tutorial covers. Phrasing it like this was suggested back when this was added.
The if-statement avoids adding the documentation to release builds of your GDExtension, where it is not needed. | ||
SCons then loads all the XML files inside the ``doc_classes`` directory, and appends the resulting targets | ||
to the ``sources`` array, to be included in your GDExtension build. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The if-statement avoids adding the documentation to release builds of your GDExtension, where it is not needed. | |
SCons then loads all the XML files inside the ``doc_classes`` directory, and appends the resulting targets | |
to the ``sources`` array, to be included in your GDExtension build. | |
The ``if`` statement avoids adding the documentation to release builds of your GDExtension, where it is not needed. | |
SCons then loads all the XML files inside the ``doc_classes`` directory, and appends the resulting targets | |
to the ``sources`` array, to be included in your GDExtension build. |
You can use the repository as a basis to build your own documentation system. | ||
The following guide describes the basic steps, but they are not exhaustive: | ||
You will need a bit of personal insight to make it work. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You can use the repository as a basis to build your own documentation system. | |
The following guide describes the basic steps, but they are not exhaustive: | |
You will need a bit of personal insight to make it work. | |
You can use the repository as a basis to build your own documentation system. | |
The following guide describes the basic steps, but they are not exhaustive; | |
you will need a bit of personal insight to make it work. |
The current documentation for documentation in godot-cpp covers everything that's necessary, but there are several things I'd like to improve:
demo
folder. Listing more assumptions than needed distracts from the contents, and might unnecessarily scare away potential readers.Documentation styling
section is duplicate to the "Class Reference Primer". The format used by Godot's class reference is the exact same as it is for GDExtension. We do not need this information twice.