glad
glad copied to clipboard
Code documentation support
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.