Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate docs in Construct compiler #243

Open
wants to merge 4 commits into
base: master
Choose a base branch
from

Conversation

Mimickal
Copy link
Contributor

@Mimickal Mimickal commented Feb 8, 2022

This PR populates the name and docs attribute for top-level Construct Structs, and the docs attribute for fields. Since Construct is Python-based, I've pulled the now-common logic for Python out to a utility.

Example ksy:

meta:
  id: docs
  endian: le
doc: |
  Example to show off Construct doc strings

  These can be multiline
  and have lots of info and stuff.
doc-ref: https://construct.readthedocs.io/en/latest/advanced.html?highlight=description#documenting-fields
seq:
  - id: field1
    type: u4
    doc: 'Short desc'
  - id: field2
    type: other
    doc: This is a cool field
    doc-ref: https://www.google.com
  - id: field3
    type: u1
types:
  other:
    seq:
      - id: sub1
        type: u4

Before this PR:

from construct import *
from construct.lib import *

docs__other = Struct(
	'sub1' / Int32ul,
)

docs = Struct(
	'field1' / Int32ul,
	'field2' / LazyBound(lambda: docs__other),
	'field3' / Int8ub,
)

_schema = docs

After this PR:

from construct import *
from construct.lib import *

docs__other = 'docs__other' / Struct(
	'sub1' / Int32ul,
)

docs = 'docs' / Struct(
	'field1' / Int32ul * 'Short desc.',
	'field2' / LazyBound(lambda: docs__other) * \
		'''This is a cool field.
		
		.. seealso::
		   Source - https://www.google.com
		''',
	'field3' / Int8ub,
) * '''Example to show off Construct doc strings

These can be multiline
and have lots of info and stuff.

.. seealso::
   Source - https://construct.readthedocs.io/en/latest/advanced.html?highlight=description#documenting-fields
'''

_schema = docs

In Python interpreter:

>>> from docs import docs
>>> docs.name
'docs'
>>> docs.docs
'Example to show off Construct doc strings\n\nThese can be multiline\nand have lots of info and stuff.\n\n.. seealso::\n   Source - https://construct.readthedocs.io/en/latest/advanced.html?highlight=description#documenting-fields\n'
>>> docs.field2.docs
'This is a cool field.\n\t\t\n\t\t.. seealso::\n\t\t   Source - https://www.google.com\n\t\t'

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant