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

Finish up sphinx domain #17

Open
klauer opened this issue Jan 15, 2022 · 2 comments
Open

Finish up sphinx domain #17

klauer opened this issue Jan 15, 2022 · 2 comments
Labels
sphinx Sphinx domain / PLC API documentation generation

Comments

@klauer
Copy link
Owner

klauer commented Jan 15, 2022

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 klauer added the sphinx Sphinx domain / PLC API documentation generation label Jan 15, 2022
@klauer
Copy link
Owner Author

klauer commented Feb 26, 2022

GVLs and PROGRAM now work as of #19

@klauer
Copy link
Owner Author

klauer commented Oct 24, 2023

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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
sphinx Sphinx domain / PLC API documentation generation
Projects
None yet
Development

No branches or pull requests

1 participant