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: | list (yml new file lines) |
| 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)
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: |
|
| 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: | list (fileLines) |
| 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: | list (inuput attributes), list (output attributes) |
| Arguments: |
|
| Keyword Arguments: |
extractClassMembersFromInitSrc
Extracts class members from a Class' init method source as list
| Constructor: | extractClassMembersFromInitSrc(src = []) |
| Return: | list (class members names) |
| 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: | string (constructor), list (class members) |
| Arguments: |
|
| 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: |
|
| 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: |
|
| 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: |
|
| Keyword Arguments: |
extractMethodsfromClassSrc
Splits a given class source to orginized dict containing it's methods sources
| Constructor: | extractMethodsfromClassSrc(src = []) |
| Return: | dict (methodName: methodSource) |
| Arguments: |
|
| 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: |
|
| 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: |
|
| 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.
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: |
|
| 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: |