Automated SKILL API Documentation

[curtisma]

Problem Statement

We would like to be able to generate API documentation of SKILL code from SKILL function docstrings in the official SKILL function docstring format which supports the Virtuoso function browser. It should produce API docs similar to the output of the Sphinx autodoc directive.

Proposed Solution

Ideally this solution would be based on Python for ease of integration with our documentation CI on GitHub but a SKILL-based solution for creating it locally could also work ok.

Alternatives Considered

• SKILLdoc-ng is an existing solution but it doesn't use the official SKILL docstring format which supports the Virtuoso function browser and it's not clear if it would support integration into our existing Sphinx-based documentation

Proposed Action Plan

• 1. we'll do this
• 2. We'll do that
• 3. Then we'll add tests for this and that.

[curtisma]

Here is the start of a method using the fdoc skill function to read the docstrings in skill.

let((Module
     (module_description "Create Virtue SKILL packages"))
    )



Module = let(()

  procedure(FunctionDocStrings(package "l")
    "Reads the documentation string for all the public functions of a package"
    let((property_symbol)
    for(property
      fdoc()
    )
  ))

  list(nil
    'New New
    'IsModule IsModule
  )
)

Module->New('Module Module Virtue
             ?description module_description)
)

[tbrandtner]

@curtisma : Did you try that fdoc call inside a Skill++ let()? Is it really returning all docstrings of the local procedures? imho it can only read the fdoc slot of symbols. And these slots are global - which means that if you access those slots later, they might contain other data - and not necessarily the docstrings of that locally defined procedures anymore.