glad icon indicating copy to clipboard operation
glad copied to clipboard

Code documentation support

Open paoloose opened this issue 1 month ago • 4 comments

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 DocsGL(SpecificationDocs) class for the GL specification, using https://docs.gl/ as source. docs.gl 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 others 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 c --with-docs

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 avatar May 18 '24 10:05 paoloose