This thread started a discussion about working on a tool that allows to pull documentation directly from (DQMH) LabVIEW source code. We should continue our discussion here.
A few people mentioned they would be interested in collaborating. As some of us will meet next week in Birmingham, we should take that opportunity to discuss some basics:
- open-source (public) or paid-for?
- scope and features (what to parse, and how to display results)
- leveraging existing tools (Tom McQuillan, Chris Cilino, ... )
- using scripts we already have
What we have is a tool I created many years ago for the framework that I ditched for DQMH. The framework is based on “kernels” (kind of the equivalent to a DQMH module), which only contain a big case structure with all the functions of a kernel. The tool pulls from the kernel VI the name, documentation, case names, case comments etc. etc and outputs text that can be copied directly to our dokuwiki. The source can be found here.
@Manu has a thing or two to say about generating the output, too. Being the python fan that he is, he wants to use https://en.m.wikipedia.org/wiki/Sphinx_(documentation_generator)
I know that others also have parts that would fit this whole thing. If and how all these things can be shared and combined, we need to find out...
I would love to have such a tool! And I'm also available to help in some way if I have the skills and the time.
My two cents here, being a Python enthusiast myself, is that Sphinx is a very mature and extensible documentation generator, it is widely documented and supported, and supports a plethora of output formats. Moreover, you also have the possibility to generate the documentation from git repos on free, automated public services such as https://readthedocs.org/.
Nice to see this project could be interesting for other people 🙂
We did a *kick off* at GDevCon with Joerg and Manu. I also discussed with Michal about Sphynx.
I have to set the project in Gitlab with all the material we already have and released it publicly.
Concerning the output there is 2 directions Sphynx and Asciidoctor.
I think we can make the tool working for both...
I'll keep everyone posted as sooon as I have the project ready.
Olivier, thanks for setting up the repository. I just pulled it and started to have a look at the code.
Nice to see other people rooting for Sphinx 😉 For the rest, not really knowing what Sphinx is, here is a nice blog post about its benefits (and some disadvantages): https://www.ericholscher.com/blog/2016/jul/1/sphinx-and-rtd-for-writers/
One more very general thing for discussion:
What LV version should we support?
Olivier, I have seen you started the project with LV 2017. Unfortunately that's the one version I don't have a ready-to-use VM for. For having a quick look at the code I just using 2018, but for a common/open development we should agree to one version.
I propose LV 2016. My feeling is that this is still the most popular version for actual projects. We at HSE going more and more to 2018, but have still a handful 2016 projects and developing our internal tools and open source tools/projects with 2016 to maintain the best compatibility.
That's only our opinion. What's your view on this topic?