generateRdFiles: Generate .Rd files for Python classes and functions

View source: R/PythonPkgWrapperUtils.R

generateRdFilesR Documentation

Generate .Rd files for Python classes and functions

Description

This function generates .Rd files for Python classes and functions in a given Python container

Usage

generateRdFiles(srcRootDir, pyPkg, container, functionFilter = NULL,
  classFilter = NULL, functionPrefix = NULL, keepContent = FALSE,
  templateDir = NULL)

Arguments

srcRootDir

The root directory under which another directory, auto-man/ is created to hold the output, Rd files.

pyPkg

The Python package name

container

The fully qualified name of a Python module, or a Python class to be wrapped

functionFilter

Optional function to intercept and modify the auto-generated function metadata.

classFilter

Optional function to intercept and modify the auto-generated class metadata.

functionPrefix

Optional text to add to the name of the wrapped functions.

keepContent

Optional whether the existing files at the target directory should be kept.

templateDir

Optional path to a template directory. Set templateDir to NULL to use the default templates in the /templates/ folder.

Details

  • container can take the same value as pyPkg, can be a module or a class within the Python package.

  • functionFilter and classFilter are optional functions defined by the caller.

  • functionFilter takes as input the metadata for a generated function and either modifies it or returns NULL to omit it from the set of generated functions. The metadata object is a list having fields:

    'name': character
    'args': named list having fields:
        'args': a list of the argument names
        'varargs':  character
        'keywords': character
        'defaults': character
    'doc': character
    'module':character
    

    Please see inspect.getargspec for more information about the named list args. See example 2.

  • classFilter takes as input the metadata for a generated class and either modifies it or returns NULL to omit it from the set of generated classes The metadata object is a list having fields:

    'name': character
    'constructorArgs': named list having fields:
        'args': a list of the argument names
        'varargs':  character
        'keywords': character
        'defaults': character
    'doc': character
    'methods':named list having fields:
        'name': character
        'doc': character
        'args': named list having fields:
            'args': a list of the argument names
            'varargs':  character
            'keywords': character
            'defaults': character
    

    Please see inspect.getargspec for more information about the named list args. See example 3.

Note

Python documentation may contains key words and terms that are only meaningful to Python users. The generated .Rd files, located in 'srcRootDir/auto-man', do not auto correct these terms, nor provide examples in R. One must copy all auto-generated .Rd files to their package /man folder and make sure that the language being used in these documents are friendly to R users.

Examples

1. Generate .Rd files for all functions and classes in "pyPackageName.aModuleInPyPackageName"
PythonEmbedInR::generateRdFiles(
  srcRootDir = "path/to/R/pkg",
  pyPkg = "pyPackageName",
  container = "pyPackageName.aModuleInPyPackageName")
  
2. Generate docs for the module "pyPackageName.aModuleInPyPackageName", omitting the function "myFun"
myfunctionFilter <- function(x) {
  if (any(x$name == "myFun")) NULL else x
}
PythonEmbedInR::generateRdFiles(
  srcRootDir = "path/to/R/pkg",
  pyPkg = "pyPackageName",
  container = "pyPackageName.aModuleInPyPackageName",
  functionFilter = myfunctionFilter)
  
3.Generate docs for the module "pyPackageName.aModuleInPyPackageName", omitting the "MyObj" constructor
myclassFilter <- function(x) {
  if (any(x$name == "MyObj")) NULL else x
}
PythonEmbedInR::generateRdFiles(
  srcRootDir = "path/to/R/pkg",
  pyPkg = "pyPackageName",
  container = "pyPackageName.aModuleInPyPackageName",
  classFilter = myclassFilter)

Sage-Bionetworks/PythonEmbedInR documentation built on April 17, 2023, 4:23 p.m.