klauer / blark

Beckhoff TwinCAT ST (IEC 61131-3) code parsing in Python using Lark (Earley)
https://klauer.github.io/blark/
GNU General Public License v2.0
42 stars 5 forks source link

Finish up sphinx domain #17

Open klauer opened 2 years ago

klauer commented 2 years ago

The sphinx domain allows for generating PLC project API documentation directly from the source code. Currently, it's pretty limited - the proof-of-concept from #12 is now in master.

A simple example might be:

conf.py

extensions = [
    "blark.sphinxdomain",
]

blark_projects = [
    "/Users/klauer/Repos/lcls-twincat-general/LCLSGeneral/LCLSGeneral.tsproj",
]
blark_signature_show_type = True

html_css_files = [
    "css/blark_default.css",
]

and the reStructuredText source:

.. bk:type:: ST_System

.. bk:function_block:: FB_TempSensor

.. bk:function_block:: FB_EtherCATDiag

    .. bk:variable_block:: VAR_OUTPUT

Where to from here? Some notes to self mostly:

klauer commented 2 years ago

GVLs and PROGRAM now work as of #19

klauer commented 10 months ago

Copying in part of my comment from #87 -

For those anxious for Sphinx support, consider sphinx-plc. I think their implementation has better sphinx integration overall that blark may borrow ideas from in the future.

Future work will be, probably roughly in this order:

1. Investigate how to better structure the domain and directives (and learn from the Python implementation, sphinx-plc, etc.)

2. Bring my doc testing repo to GitHub so that others can more easily try blark's sphinx support

3. Rework/rewrite it in a submodule, breaking up the pieces a bit more (`blark.sphinxdomain.*` perhaps)