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

ENH: initial attempts at code summary layer, sphinx domain #12

Merged
merged 32 commits into from
Jan 15, 2022
Merged

Conversation

klauer
Copy link
Owner

@klauer klauer commented Nov 25, 2021

Changes in no particular order

  • Reworked how Meta instances are transferred over from lark to blark; add explicit dataclass attributes for them
  • Trying out a layer that summarizes transformed code for easier access ("tell me the function blocks, their declared variables/methods/actions, and where to find them")
  • Building a sphinx Domain on top of it (looking at sphinx-julia, built-in Python support for inspiration/ideas how to do it)
  • Rework some weird code flow from the original blark parse CLI
  • Some test cleanup
  • More test coverage for global var declarations
  • Made mypy a lot happier for blark.transform (never 100% happy of course)
  • Add UNION support (Closes Add support for UNION (TYPE) #14 )
  • Additional grammar fixes (need to document more of the differences noted when running TwinCAT. As to be expected, blark is more permissive in some cases and too restrictive in others)

Documentation?

So far, just function blocks + methods:
image

Generated by way of pointing to the project in Sphinx conf.py:

.. bk:functionblock:: FB_TempSensor
  • Cross-referencing works with function block names, variable/method names.
  • Functions, programs, etc. will be easy enough to add when I get time
  • No intention of making sphinx or docutils a required runtime dependency to blark

Things which I don't have a clue how to approach just yet:

  • Cross-referencing API docs from source code listings
  • And some form of syntax highlighting
  • Autodoc (project -> auto-documented pages)

@klauer
Copy link
Owner Author

klauer commented Dec 3, 2021

Despite the above, I'm going to redo this entirely working with docutils.nodes and sphinx addnodes (removing Jinja from the equation). It's a more standard way of doing things, though I'm not finding much documentation on how those nodes should be structured, so it may take a bit.

@klauer klauer mentioned this pull request Dec 14, 2021
@klauer klauer changed the title WIP: Code summary layer, initial attempt at sphinx domain, ... ENH: initial attempts at code summary layer, sphinx domain Jan 15, 2022
@klauer
Copy link
Owner Author

klauer commented Jan 15, 2022

There's still a lot left to do here, but the structure is OK enough as-is to merge for now.

There will be follow-ups down the line at some point. One day entire PLC projects' API will be easily documentable in sphinx, but today is not that day...

@klauer klauer merged commit 21e35de into master Jan 15, 2022
@klauer klauer deleted the summary branch January 15, 2022 00:47
@klauer klauer mentioned this pull request Jan 15, 2022
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.

Add support for UNION (TYPE)
1 participant