Documenting Python Libraries with 3rd Party Tools

[srunde]

Has anyone had success aggregating docstrings from Python libraries into a tool like MkDocs and its accompanying plugins? I’d like to use mkdocstrings, but the inability to import script as it’s structured in the Ignition file system (no init.py files and modules are stored as code.py) is a hinderance.

[justin.brzozoski]

Nothing useful to add, except that I was facing similar issues while goofing around with type annotations and mypy.

Running mypy or other static type-checking on Ignition Jython scripts

On Python projects unrelated to Ignition, I’ve been starting to use type annotations and static type checking tools like mypy. I find the type annotations very helpful as reminders of what function parameters are supposed to be, and mypy helps find corner cases that would’ve lead to exceptions. If you’ve never seen type annotations in Python, the mypy cheat sheets are the simplest demonstration and practical explanation I’ve found. Annotations used to be stored as comments in Python2, but Pytho…

Didn't come up with any good solutions (yet), but I haven't stopped trying. This is just a "would be nice to have" feature in our setup, so I haven't been able to dedicate much time to it.

[Jeff_Krol]

I'm trying to figure this problem out now. So far, I've tried:

• pydoc: this kind of worked as a command line option, but I'm having a hard time creating a Python script that loops through all code.py files and then renames the appropriate code.html file with the appropriate Script library name. Part of the problem is that this appears to be designed for installed Python modules. I'm thinking this is probably just a skill issue, and I just need to figure out what I'm doing wrong.
• pdoc3: has to import the script to function and since Ignition scripts use Python 2.7, there are lots of issues you'll run into. I've tried using an older version 0.3.13 but I couldn't get that to run as the module 'imp' doesn't appear to exist anymore

[Jeff_Krol]

Alright I gave it another try with my pydoc script using os.system to just call pydoc from the command line as that worked pretty well. Here is my Python script. Sorry it's not documented yet!

Also, I need to clean this up a little bit as there are some string variables that probably shouldn't be here.

import os, shutil
import pydoc

folderPath = r'C:\Program Files\Inductive Automation\Ignition\data\projects\SCADA\ignition\script-python'

# Find all of the subfolders
subFolders = os.walk(folderPath)

# Loop through all of the subfolders
for (root,dirs,files) in subFolders:
    # If the folder contains a 'code.py' file, then it contains an Ignition Python script
    if "code.py" in files:
        scriptLibraryName = root.replace(folderPath,"")
        scriptDocPath = "doc" + root.replace(folderPath,"")
        print(scriptDocPath)
        scriptCWD = os.getcwd()
        fullScriptDocPath = scriptCWD + "\\" + scriptDocPath
        os.makedirs(fullScriptDocPath, exist_ok = True)
        fullCodePyPath = root + "\\" + "code.py"
        print(root)
        try:
            commandToExecute = f'pydoc -w "{fullCodePyPath}"'
            os.system(commandToExecute)
            #pydoc.writedoc(root + "\\" + "code.py")
        except Exception as e:
            print(e)
            fileFlags = os.O_CREAT | os.O_RDWR
            fd = os.open(scriptCWD + "\\" + "code.html", fileFlags)
            os.write(fd,b"No documentation found!")
            os.close(fd)
        shutil.copy(scriptCWD + "\\code.html", fullScriptDocPath)