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 --with-docs c

Thinks to know:

• Currently, only commands are documented.
• Documentation code is optional and included only when the --with-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.