Is there a standard way to document the larger capabilities of a project? I’m aware of documentation fields in tags, docstrings in python libraries, etc., but I’d also like to integrate bigger-picture documentation.
For example, I might create a python package that automates the generation of some Ignition resources based on a csv import. It’s possible to write a huge docstring, but improved formatting like Markdown and navigation between examples, usage, FAQ, etc. would be nice. Has anyone found success documenting this close to project (i.e. in some Ignition resource), or is it easier to keep the documentation files elsewhere?
This is actually something we’re interested in first-party; we just haven’t spent the time to really nail down requirements.
As a (baby) step forward, in 8.1.19 you’re able to attach (plain text) documentation to every resource in the designer. We’ve talked about having a module or platform feature that would go through the project and serve up a navigable webpage, something like what a static site generator could do with a Python library. I’m also actively working on code completion for project scripts, which will include the docstring, which further helps with usability/discoverability.
This isn’t quite first-party, but we put readme markdown files all over the place in our projects.
This works well when version controlling and using something like GitHub to show you all of the details.
Only comment is if you are doing it for a specific view, make sure you add it to the resource.json list of files or Ignition will delete it right out from under you when its bored!