Code documentation support

[paoloose]

This PR adds support for optional code documentation as requested in #247.

Basically, Specification classes can now include documentation from a language-agnostic SpecificationDocs class, which knows how to retrieve and parse the specs documentation from a specific source.

As a proof of concept I've implemented the OpenGLRefpages(SpecificationDocs) class for the Open GL Refpages specification, using https://github.com/KhronosGroup/OpenGL-Refpages as source. OpenGL-Refpages was definitely not created to be parser-friendly, but I managed to properly parse all the commands docs (without including tables and code blocks for now).

Additional sources will be needed for other specifications. Currently I'm only planning to contribute with the GL spec docs. Others can be added later with no problems.

Looking forward to feedback and willing to implement any requested modification. Thanks!

Test with:

# Use the --with-docs flag
python -m glad --extensions="" --api="gl:compatibility=" --out-path ./temp --docs c

Thinks to know:

• Currently, only commands are documented.
• Documentation code is optional and included only when the --docs flag is present. If the given specification doesn't support docs, only a warning is shown.
• Documentation was only added to C templates, but can be easily added to Rust templates also.

[paoloose]

This is how hovering a command looks in vscode

[Dav1dde]

Thanks for putting in the work, initial thoughts:

• I'd prefer if it not depended on external tools and call processes with subprocess, it should be possible to just download a zip/tar file instead.
• I wouldn't want to depend on docs.gl but instead the Khronos repo OpenGL-Refpages (except if there is a good reason to depend on docs.gl).
• I thought this could be a maintenance nightmare but the docs don't seem to be changed very often (probably different for Vulkan ...)

[paoloose]

I wouldn't want to depend on docs.gl but instead the Khronos repo OpenGL-Refpages (except if there is a good reason to depend on docs.gl).

Seems good to me. I'll be replacing DocsGL with that source. I understand that docs.gl is more a community driven documentation than a strict reference. I was also consider shipping both, but from a maintainer point of view docs.gl is not convenient.

Working on resolving the other requested changes :)

[Dav1dde]

I understand that docs.gl is more a community driven documentation than a strict reference.

I assumed it is based on the same OpenGL-Refpages repo just already processed for better display on docs.gl but without additional curation.

[paoloose]

I assumed it is based on the same OpenGL-Refpages repo just already processed for better display on docs.gl but without additional curation.

See https://docs.gl/about.html. It adds additional information to the official specs (even typo fixes) and allows contributions, but yeah, what was said about maintenance still holds. Still working on parsing Khronos reference.

[Dav1dde]

Thanks for putting in all the work and sorry for being so unresponsive slow, I just don't have the mental bandwidth atm.

[paoloose]

Thanks for putting in all the work and sorry for being so unresponsive slow, I just don't have the mental bandwidth atm.

No worries, thank you for taking the time to review it. I'm dogfooding this docs while I'm working in some OpenGL projects, so I'll be pushing fixes as I encounter more issues. For now I've implemented the requested changes. Wish the code was more elegant, but Khronos really worked hard to make their documentation format a parsing nightmare haha.

[MrLuigiBean]

Hello, apologies for reviving this old thread, but are the changes from this branch going to be added to the default branch? I'd love to have documentation generated and visible when hovering over functions to make development a little easier.

[eloj]

Just an update on the OpenGL-RefPages situation.

Khronos (perhaps understandably) hasn't been paying too much attention to the repo, but I pinged Jon Leech of Khronos last week, and he got the GL 4.6 pages and many, many other pending pull requests merged.

There are still a couple PRs (glGet args, min tex sizes) with fixes pending, but now the original source is much more up-to-date.

(BTW: I added GLAD to the OpenGL-RefPages tools list on the index page)

[eloj]

Anyway, I have tested this branch against the updated specification, and it seems to work after the following changes:

• A rebase is needed. The only conflict is in .gitignore, so easily resolved.
• One of the XML files (gl4/glPolygonOffsetClamp.xml) now contains an { entity, so something like the following patch is required.

diff --git a/glad/util.py b/glad/util.py
index bc5ca54..ff07843 100644
--- a/glad/util.py
+++ b/glad/util.py
@@ -267,6 +267,8 @@ math_symbols_map = {
     '⌉': '⌉',
     '∥': '∥',
     '∣': '|',
+    '{': '{',
+    '}': '}',
 }

Probably the handling of entities could be made more robust.

[eloj]

The main deficiency I see with this branch at this point, is that the --docs option is not reflected in generated template output (e.g include/glad/gl.h).

I can see that 'docs' is not present in the gen_info in the Commandline.build() method, but honestly after 20 minutes of trying to figure how this is supposed to flow, I gave up. For now.

[paoloose]

Thanks for putting in the work! I've implemented the two changes you mentioned, but don't currently have the time to check the --docs bug

Happy to see this branch getting some attention again :)