Add gdscript-xml-docs.el

[drcxd]

This allows users browse the XML documentation which comes along with the engine source code. The feature tries to mimic the workflow when working in the engine editor, pressing F1 to search and read offline documentation.

I have only contributed to another open-source project once before. Though I am not new to programming, I am new to emacs-lisp. There are a lot of improvements to be made. For example,

• All the links have not been correctly handled yet.
• Code blocks need better formatting.
• Inheritance information is not displayed.
• Internal or even external link can be implemented.
• setters/getters are not properly handled.

However, currently the code should work and be useful. Please let me know what I should improve further.

[xiliuya]

Hello, @drcxd . I downloaded and tried to test your branch. But I faced the following questions:

1. How do I get an xml doc? I found it in the system directory: /usr/share/mime/packages/org.godotengine.Godot.xml . It's confusing to me. I think that needs a variable to define.
2. How do I use it ? When I executed 'gdscript-xml-docs-open' I got the following output:

   Unhandled node tag: mime-info
   Unhandled node tag: mime-type
   Unhandled node tag: comment
   Godot Engine projectUnhandled node tag: sub-class-of
   .....

3. You need to add (require 'gdscript-xml-docs) to gdscrpit-mode.el for autoload.
4. About string-lines: An Error : You should depend on (emacs "28.1") if you need 'string-lines'. Problems with the emacs version of string-lines will result in the entire package being dependent on emacs 28.1, so we may have to try to find other functions to work around this,like split-string.

[drcxd]

Hello @xiliuya,

Sorry for coming back so late, my full-time job had became stressful last year, so I somehow lost my interest about independent projects.

1. How do I get an xml doc? I found it in the system directory: /usr/share/mime/packages/org.godotengine.Godot.xml . It's confusing to me. I think that needs a variable to define.

I have added a custom variable gdscript-xml-docs-local-path which should points to the classes directory in the engine source code. The relative path from the root of the engine directory is ./doc/classes.

2. How do I use it ? When I executed 'gdscript-xml-docs-open' I got the following output:

Unhandled node tag: mime-info
Unhandled node tag: mime-type
Unhandled node tag: comment
Godot Engine projectUnhandled node tag: sub-class-of
.....

I have not tested all the documents. Until now, I mainly use String.xml to test the code. If succeed, you should see a similar buffer like this:

3. You need to add (require 'gdscript-xml-docs) to gdscrpit-mode.el for autoload.

Thanks for pointing that out. I missed.

4. About string-lines: An Error : You should depend on (emacs "28.1") if you need 'string-lines'. Problems with the emacs version of string-lines will result in the entire package being dependent on emacs 28.1, so we may have to try to find other functions to work around this,like split-string.

This one is a little bit difficult. I have tried split-string, but I can not make it do what string-lines do for me. I tried to copy the implementation of string-lines into an Emacs 26.3, but it depends on a C function that is introduced in Emacs 28, namely string-search, which renders the mission impossible. So currently I do not know how to deal with this.

Looking back what I have done about a year ago, my vision is to replicate the working flow of browsing local documentation inside the Godot eidtor by pressing F1. I have tried to using eww to browsing html doc, but it is not efficient. So I try to parse the xml doc and display the content in a org-mode buffer. However, there are still lots of things to do to make it comparable with the in-editor documents.

Today, I just discovered that godot-doc can be built to texinfo format. I have tried it, the result is hopeful but is not viable in the current stage. The index of the document only contains 23 entreis, which makes searching by topics, classes, or methods impoosible and the content is ill-formed.

For example, the index does not contain String or any other class, so I can not quickly locate what I am looking for. After I somehow locate the document for String, it contains the following content:

Looks like all the links are prepended with "See"/"see". The content is not properly formatted: not all code are displayed using monospace fonts. However, this is still much better than my work, since it keeps all the links and I think it is hard or impossible to implement these links in my way.

So I think I should stop trying to render the doc in org-mode. Instead, I should make the compiled info doc better, by adding indices and polish the formatted contents. However, I have totally no idea how to achieve this, since I know nothing about sphinx and nearly nothing about texinfo, not to mention how to convert from one to another.

Do you have any suggestions? Thanks a lot.