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:
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: None Arguments:
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:
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)
Constructor: buildFileDoc(path, ymlPath) Return: None Arguments:
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:
Keyword Arguments:
buildReleaseNotesPage
Constructor: buildReleaseNotesPage(mkDocksYmlPath) Return: None Arguments:
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: None Arguments:
Keyword Arguments:
collectHeaderFromCppFile
For the given cpp file, extract the header comment.
Constructor: collectHeaderFromCppFile(cppFullPath = None) Return: None Arguments:
Keyword Arguments:
commitAndDeployDocumentation
Constructor: commitAndDeployDocumentation(rootDrive = "d", relativeDirectory = "mansurProject\mansur-docs", kwargs) Return: None Arguments:
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:
Keyword Arguments:
extractAttributeDefenitionsFromCppFile
From the given cpp path given, extract all attribute information.
Constructor: extractAttributeDefenitionsFromCppFile(cppFullPath = None, buildName = None) Return: None Arguments:
Keyword Arguments:
extractClassMembersFromInitSrc
Extracts class members from a Class' init method source as list
Constructor: extractClassMembersFromInitSrc(src = []) Return: None Arguments:
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: None Arguments:
Keyword Arguments:
extractDocsForClass
Wrapped def.
Extracts full documentation from a given class source.
Constructor: extractDocsForClass(classSrc = []) Return: None Arguments:
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: None Arguments:
Keyword Arguments:
extractHeaderFromSrc
Extracts a header if exsits from a given elemnt src (Class/Def/Method) as list
Constructor: extractHeaderFromSrc(src = [], kwargs) Return: None Arguments:
Keyword Arguments:
extractMethodsfromClassSrc
Splits a given class source to orginized dict containing it's methods sources
Constructor: extractMethodsfromClassSrc(src = []) Return: None Arguments:
Keyword Arguments:
extractParametersFromDefSrc
Extract parametrs from a given def source as list
Extracts arguments and optional arguments
Constructor: extractParametersFromDefSrc(src = []) Return: None Arguments:
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: None Arguments:
Keyword Arguments:
getParameterForMnsArg
Extracts arguments from a given def source lines as list
Constructor: getParameterForMnsArg(arg) Return: string (flattened combined arguments) Arguments:
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.
Constructor: getPyLibForDir(root) Return: None Arguments:
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:
Keyword Arguments: