Code documentation support #471
Conversation
paoloose
force-pushed
the
glad2-inline-docs
branch
from
3ac71f0
to
3a15146
Compare
|
This is how hovering a command looks in vscode |
Forgot to add spaces when listing ('-') <dt> elements.
Also, the regex was improperly removing contiguous line breaks.
|
Thanks for putting in the work, initial thoughts:
|
| @@ -1453,3 +1478,52 @@ def from_element(cls, element, api=None): | |||
| def __str__(self): | |||
| return '{self.name}@{self.version!r}'.format(self=self) | |||
| __repr__ = __str__ | |||
|
|
|||
|
|
|||
| class SpecificationDocs(object): | |||
There was a problem hiding this comment.
I think this fits better in the documentation module
There was a problem hiding this comment.
I based the documentation,py module on how the specification.py is structured: just classes that inherit from the base Specification class defined in parse.py. So documentation.py holds specialized classes that inherit from the base SpecificationDocs class, also defined in parse.py.
glad/parse.py
Outdated
| @@ -732,6 +747,15 @@ def select(self, api, version, profile, extension_names, sink=LoggingSink(__name | |||
| extensions = [self.extensions[api][name] for name in extension_names | |||
| if name in self.extensions[api]] | |||
|
|
|||
| # Load documentation for the specific configuration | |||
| if config['WITH_DOCS']: | |||
There was a problem hiding this comment.
Seems like the specification doesn't need the docs at all. Instead of tying the docs to the specification, the templating could be the part where the specification gets married with the docs.
There was a problem hiding this comment.
Can you please elaborate on this? The specification doesn't depend on the docs, but the docs need to know what specification are they documenting, and specifications need to know what documentation sources they have available, for example, if we support multiple sources in the future.
How can I define this relation in the templating process?
There was a problem hiding this comment.
I am not quite sure about how I'd like it to look at the end, don't worry too much about it, it's easy for me to just move everything a bit around.
But basically in mind right now the docs are a separate source of data independent of the spec and you just pass it as some kind of "docs db" into the template and the template tries to lookup the docs from the db when rendering.
What guarantuess you get the correct symbols? Either it's in the template, a similar mechanism to spec.select() or just nothing, if you pass the wrong docs then there are just no docs for the requested symbols.
But again don't worry too much about that, these are the things that are easy to change later, the hard part is the actual logic!
There was a problem hiding this comment.
I moved this logic and now docs are loaded separately, only for the specifications listed by the user. Then, those loaded docs sources are "selected" from a feature_set, and passed directly to the template generator function, without depending on the spec. I think I ended up understanding what you meant, but if not, feel free to change it later. I'll be working on using the Khronos Refpages as source :-)
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 :) |
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. |
I needed the 'recover' kwarg, since some xml files were broken. See <https://lxml.de/api/lxml.etree.XMLParser-class.html>.
- load lxml module first, and fallback to xml module - don't extract zip file to parse the documents - fix other formatting issues that I encountered
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. |
This PR adds support for optional code documentation as requested in #247.
Basically,
Specificationclasses can now include documentation from a language-agnosticSpecificationDocsclass, 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 theGLspecification, 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:
Thinks to know:
--with-docsflag is present. If the given specification doesn't support docs, only a warning is shown.