Skip to content

docBuildMansur


=== Author: Assaf Ben Zur ===

Core procedural documentation build

Process flow:

Read a given directory

Build a structure based on the os directory given and the folders to filter

Filter only .py files

For each py file:

    Extract Header (such as this one)

    Extract Defenition

        Extract Def name and constructor

        Extract Arguments, and Optional Arguments

        Extract return

    Extract Classes

    Extract Header

    Extract Name and constructor

    Extract inheritence

    Extract Class members

    Extract Methods

        Extract Header

        Extract Name and constructor

        Extract Arguments and Optional Arguments

        Extract return

rebuild the yml file given

write the files within the 'docs' directory

This procedural approach for a code documentation build ensures an up-to-date documentation based on code commenting.

No additional actions are neccessery.

This will yeild a readable commented code with will math the documentation 1-to-1.

Also, this will yeild a very "easy to change" approach for the documentation generator of choice as well as a 100% cohirent documentation throuout.



Defenitions


appendMayaPluginsToYml

Append the Maya-Plugins documentation page into the existing yml struct.


Constructor: appendMayaPluginsToYml(ymlPath, parentPageName)
Return: None
Arguments:
  • ymlPath
  • parentPageName
Keyword Arguments:


buildDocItems

Main dir build recursive function.

The function builds only directory items, which in turn will be searched for '.py' files, and will be added to the structure only if in contains a direct '.py' within,

or if a directory within comatins one, recursively.

Depth independent.


Constructor: buildDocItems(dir, rootDir, level, ymlPath, fileLines)
Return: list (yml new file lines)
Arguments:
  • dir
  • rootDir
  • level
  • ymlPath
  • fileLines
Keyword Arguments:


buildDocsForDir

Main build wrapper and the yml file writer wrapper function.

Calls 'buildDocItems' within which in turn build the actual html files within the 'docs' directory.

Finally re-writes the yml file using 'rebuildYmlFile' according to the file structure acquired


Constructor: buildDocsForDir(mkDocksYmlPath, parentPageName, directory, folders, level = 0)
Return: None
Arguments:
  • mkDocksYmlPath
  • parentPageName
  • directory
  • folders
  • level(int) ; [default: 0]
Keyword Arguments:


buildFileDoc

Main file def.

This is a wrapped def as well as a function one.

Compiles all needed documentation from a given file path.

Will compile Classes, methods, defenitions (icluding all relevant information for each)

This is also the main WRITE defenition. After info assembly the info will be written as a new file, overriding existing ones, to create a new doc page.

Any file doc 'display' is contained within this def.


Constructor: buildFileDoc(path, ymlPath)
Return: None
Arguments:
  • path
  • ymlPath
Keyword Arguments:


buildMansurDocs

Main wrapper call for the MANSUR directory doc build.

Contains the requested folders within, hard-coded for safety.


Constructor: buildMansurDocs()
Return: None
Arguments:
Keyword Arguments:


buildModSettingsFileDoc

Constructor: buildModSettingsFileDoc(path, ymlPath)
Return: None
Arguments:
  • path
  • ymlPath
Keyword Arguments:


buildReleaseNotesPage

Constructor: buildReleaseNotesPage(mkDocksYmlPath)
Return: None
Arguments:
  • mkDocksYmlPath
Keyword Arguments:


buildSubItemsDir

Last level recursive function.

This function will call the documentation file build as well as build the last meanu item within the structure.

The final pythonLib item is passed in, as well as the root directory and the current level and the yml path in order to write the new yml lines correctly, depending on the file's level position.


Constructor: buildSubItemsDir(rootDir, pyLib, level, ymlPath, fileLines)
Return: list (fileLines)
Arguments:
  • rootDir
  • pyLib
  • level
  • ymlPath
  • fileLines
Keyword Arguments:


collectHeaderFromCppFile

For the given cpp file, extract the header comment.


Constructor: collectHeaderFromCppFile(cppFullPath = None)
Return: None
Arguments:
  • cppFullPath(str) ; [default: None]
Keyword Arguments:


commitAndDeployDocumentation

Constructor: commitAndDeployDocumentation(rootDrive = "d", relativeDirectory = "mansurProject\\mansur-docs", **kwargs)
Return: None
Arguments:
  • rootDrive(str) ; [default: "d"]
  • relativeDirectory(str) ; [default: "mansurProject\\mansur-docs"]
  • **kwargs
Keyword Arguments:


createPluginDocFile

Create the Maya-Plugins attributes documentation page.


Constructor: createPluginDocFile(rootBuildPath = "D/mansurProject/mayaPlugins", ymlPath = "D/mansurProject/mansur-docs/mkdocs.yml")
Return: None
Arguments:
  • rootBuildPath(str) ; [default: "D:/mansurProject/mayaPlugins"]
  • ymlPath(str) ; [default: "D:/mansurProject/mansur-docs/mkdocs.yml"]
Keyword Arguments:


extractAttributeDefenitionsFromCppFile

From the given cpp path given, extract all attribute information.


Constructor: extractAttributeDefenitionsFromCppFile(cppFullPath = None, buildName = None)
Return: list (inuput attributes), list (output attributes)
Arguments:
  • cppFullPath(str) ; [default: None]
  • buildName(str) ; [default: None]
Keyword Arguments:


extractClassMembersFromInitSrc

Extracts class members from a Class' init method source as list


Constructor: extractClassMembersFromInitSrc(src = [])
Return: list (class members names)
Arguments:
  • src(list) ; [default: []]
Keyword Arguments:


extractConstructorValuesForClass

Extracts constructor related values from a class source as list.

Wrapper def.

Extracts both Arguments (flattened) and class members


Constructor: extractConstructorValuesForClass(src = [])
Return: string (constructor), list (class members)
Arguments:
  • src(list) ; [default: []]
Keyword Arguments:


extractDocsForClass

Wrapped def.

Extracts full documentation from a given class source.


Constructor: extractDocsForClass(classSrc = [])
Return: string (title), list (header), string (sontructor), string (inherit object), list (class members), string (return)
Arguments:
  • classSrc(list) ; [default: []]
Keyword Arguments:


extractDocsForDef

Wrapper def for a full doc extraction for a given file souce as list.

extracts return statement, title, header, arguments and optionalArguments


Constructor: extractDocsForDef(defSrc = [])
Return: string(title), list(header), list(arguments), list(optionalArguments, string(return statement)
Arguments:
  • defSrc(list) ; [default: []]
Keyword Arguments:


extractHeaderFromSrc

Extracts a header if exsits from a given elemnt src (Class/Def/Method) as list


Constructor: extractHeaderFromSrc(src = [], **kwargs)
Return: list (header lines)
Arguments:
  • src(list) ; [default: []]
  • **kwargs
Keyword Arguments:


extractMethodsfromClassSrc

Splits a given class source to orginized dict containing it's methods sources


Constructor: extractMethodsfromClassSrc(src = [])
Return: dict (methodName: methodSource)
Arguments:
  • src(list) ; [default: []]
Keyword Arguments:


extractParametersFromDefSrc

Extract parametrs from a given def source as list

Extracts arguments and optional arguments


Constructor: extractParametersFromDefSrc(src = [])
Return: list (arguments) , list(optionalArguments)
Arguments:
  • src(list) ; [default: []]
Keyword Arguments:


gatherPluginDocumentation

From the build directory given, extract attributes data directly from the cpp files.

compile the data into input/uotput lists containing dict info for all attributes.


Constructor: gatherPluginDocumentation(rootBuildPath = "D/mansurProject/mayaPlugins")
Return: list (build list containing extracted attributes data)
Arguments:
  • rootBuildPath(str) ; [default: "D:/mansurProject/mayaPlugins"]
Keyword Arguments:


getParameterForMnsArg

Extracts arguments from a given def source lines as list


Constructor: getParameterForMnsArg(arg)
Return: string (flattened combined arguments)
Arguments:
  • arg
Keyword Arguments:


getPyLibForDir

This is a complex recursive function that will assemble a file structure from a given path directory.

The assembly will filter ONLY folders that contain at least one '.py' file, and ONLY '.py' files.

This function returns a dictionary containing the file and folder structure as keys "dirs" and "files" respectively.

As this is a recusrsive depth independent function, the return will be a complex compound dict, which contains instances of the same dict structure within.

This is dependent of depth obviously-

if a directory contains another directory within- which contains a '.py' the first item "dirs" key will contain another dictionary containing a "dirs" key and a "files" key.

Ultimatly, the first dict "dirs" key should contain a single complex dict element.


Constructor: getPyLibForDir(root)
Return: dict (complex library dict)
Arguments:
  • root
Keyword Arguments:


rebuildYmlFile

yml writer function.

Writes the given yml file passed, with the new 'lines' passed.

The yml 'parentPageName' is passed as an argument - the new 'lines' build is constructed underneeth.

Existing required info is preserved by calculating the parent item indentation level, keeping every item with lower or matching level.

Every item under the parent item passed in a higher level is removed or reconstructed.


Constructor: rebuildYmlFile(ymlPath, parentPageName, lines)
Return: None
Arguments:
  • ymlPath
  • parentPageName
  • lines
Keyword Arguments: