Since Python 3.5+ is required, we can use proper type hints based on PEP 484. Because we are working on contributor tooling we can assume 3.6+ and use PEP 526 for variable declarations as well.
When generating rst files from xml class reference, unknown references
to operators were generated, as something like:
:ref:`operator <<class_Vector2_operator_lt_bool>`
was rendered in html as:
operator ( Vector2 right )
-it just needed escaping.
The small addendum checks for operator names containing '<' and
substitutes it with '\<', escaping at rst level and generating
instead the right rendered html:
operator < ( Vector2 right )
This affected mostly the reference pages of the VectorX family of
classes. If in the future more types need escaping, a more
general solution will be needed.
This is automatically enabled on all platforms including
Windows 10 and later, whenever a TTY environment is detected.
In non-TTY environments such as CI, this can be forced using the
`--color` command line argument.
When converting doc xml files to rst, add an indenation level to bullet points in the text description of enum values.
Also add check to avoid out of bounds error in rstize_text.
- List file names before error descriptions, as is common in linters.
- Print the number of errors reported at the end of the list.
- Use double quotes instead of single quotes in messages.
Using codespell 2.2-dev from current git.
Added `misc/scripts/codespell.sh` to make it easier to run it once in a
while and update the skip and ignore lists.
This makes it possible to change the branch of the documentation that
URLs are pointing to without having to modify all class reference
files.
In the XML class reference, the `$DOCS_URL` placeholder should be used,
and will be replaced automatically in the editor and when generating
the RST class reference.
The documentation branch string is set in `version.py`.
Co-authored-by: Hugo Locurcio <hugo.locurcio@hugo.pro>
* Allows calling into native extensions directly with a pointer
* Makes it easier to implement some APIs more efficiently
* Appears with a "*" in the documentation for the argument.
* Implementing the pointer handling is entirely up to the implementation, although the extension API provides some hint.
* AudioStream has been implemented as an example, allowing to create NativeExtension based AudioStreams.
- Escape the method names as e.g. `operator <` is invalid XML.
- Add a hack to merge all String % operator definitions for each Variant type
as a single one with `Variant` argument type.
- Add support for the new qualifiers in makerst.py.
- Drop unused `doc_merge.py`, seems to date back to when we had all the
documentation in a single `classes.xml`.
Configured for a max line length of 120 characters.
psf/black is very opinionated and purposely doesn't leave much room for
configuration. The output is mostly OK so that should be fine for us,
but some things worth noting:
- Manually wrapped strings will be reflowed, so by using a line length
of 120 for the sake of preserving readability for our long command
calls, it also means that some manually wrapped strings are back on
the same line and should be manually merged again.
- Code generators using string concatenation extensively look awful,
since black puts each operand on a single line. We need to refactor
these generators to use more pythonic string formatting, for which
many options are available (`%`, `format` or f-strings).
- CI checks and a pre-commit hook will be added to ensure that future
buildsystem changes are well-formatted.
- Duplicate the header when the `-a` flag is enabled. Since lots of
items are displayed in this case, this helps the user remember
which column is which without having to scroll back to the top.
- Bolden the overall percentages for easier visual grepping.
We already removed it from the online docs with #35132.
Currently it can only be "Built-In Types" (Variant types) or "Core"
(everything else), which is of limited use.
We might also want to consider dropping it from `ClassDB` altogether
in Godot 4.0.
- Drop the "Brief description" header as it became redundant
with this change.
- Fix a bug in the editor help where an extraneous newline was added
after the header if the class isn't inherited by any others.
- Remove the Category line in the rST markup as it's not useful
for API users.
Moved some logic to make_url in an attempt to reuse it in the parser,
but it proved too complex so I ended up not using it. I kept it as a
separate method nevertheless.
Enum reference resolving will now search in the @GlobalScope if no class is specified and the enum cannot be resolved in the current class.
Added support for constant references in EditorHelp, e.g.: [constant KEY_ENTER] or [constant Control.FOCUS_CLICK]. It supports enum constants (the enum name must not be included).
It's now smart and keeps track of every entity in the doc files. Now it can pick up on broken references and such inside the doc files.
Eventually we'll be able to run it on Travis and check for errors automatically.
General file cleanup.
References to elements of classes now have a prefix for their type. class_Control_minimum_size_changed becomes class_Control_method_minimum_size_changed, or signal_, because the reason I did this was to fix reference conflicts.
You can also reference constants now with BBCode.
Also made it use argparse, adding an --output and a --dry-run argument.
I did not fix all the errors it's reporting in the documentation files, there's about 150+ of them but that's outside of the scope of this commit.
Man this file even had some semicolons in it.
I cleaned up the entire file, while it's still pretty ugly it's much better now.
I also added type checks so it passes mypy --strict.
make_type now throws a warning on unresolved type references, which there are a bunch of. I'm not responsible for fixing those though.
Also some more hardening against crashes. For example XML tags without content won't cause crashes now.
Functionality has not been modified as far as I can tell.
Update Makefile for Python 3
Fix ordering issues related to enums & constants
There is now an overview table with hyperlinks, and further down a detailed
list of properties with their setter/getter and description.
Theme items are now also included in the rst output.
Refactored make_method() a bit.
We were not consistently applying .lower() every time we construct
an hyperlink, so there would be case mismatch. It works fine to keep
the natural case for those links.
