Autogenerate Documentation with Sphinx (#181)

* First try for Sphinx documentation * Add more documentation * Prepare for more documentation-generation * Fixup build
Autodesk · Aug 2, 2022 · 2935c77 · 2935c77
1 parent 4801967
commit 2935c77
Show file tree

Hide file tree

Showing 9 changed files with 597 additions and 46 deletions.
diff --git a/Build/build.bat b/Build/build.bat
@@ -3,7 +3,7 @@ set startingDir="%CD%"
 set basepath="%~dp0"
 
 cd %basepath%\..\Source
-set Sources=actutils.go automaticcomponenttoolkit.go buildbindingccpp.go buildbindingcsharp.go buildbindinggo.go buildbindingnode.go buildbindingpascal.go buildbindingpython.go buildimplementationcpp.go buildbindingjava.go buildimplementationpascal.go componentdefinition.go componentdiff.go languagewriter.go languagec.go languagecpp.go languagepascal.go
+set Sources=actutils.go automaticcomponenttoolkit.go buildbindingccpp.go buildbindingccppdocumentation.go buildbindingcsharp.go buildbindinggo.go buildbindingnode.go buildbindingpascal.go buildbindingpython.go buildimplementationcpp.go buildbindingjava.go buildimplementationpascal.go componentdefinition.go componentdiff.go languagewriter.go languagec.go languagecpp.go languagepascal.go
 
 set GOOS=windows
 set GOARCH=amd64

diff --git a/Build/build.sh b/Build/build.sh
@@ -9,7 +9,7 @@ startingpath="$(pwd)"
 basepath="$(cd "$(dirname "$0")" && pwd)"
 cd "$basepath/../Source"
 
-Sources="actutils.go automaticcomponenttoolkit.go buildbindingccpp.go buildbindingcsharp.go buildbindinggo.go buildbindingnode.go buildbindingpascal.go buildbindingpython.go buildbindingjava.go buildimplementationcpp.go buildimplementationpascal.go componentdefinition.go componentdiff.go languagewriter.go languagec.go languagecpp.go languagepascal.go"
+Sources="actutils.go automaticcomponenttoolkit.go buildbindingccpp.go buildbindingccppdocumentation.go buildbindingcsharp.go buildbindinggo.go buildbindingnode.go buildbindingpascal.go buildbindingpython.go buildbindingjava.go buildimplementationcpp.go buildimplementationpascal.go componentdefinition.go componentdiff.go languagewriter.go languagec.go languagecpp.go languagepascal.go"
 export GOARCH="amd64"
 
 echo "Build act.exe"

diff --git a/README.md b/README.md
@@ -56,19 +56,19 @@ Alternatively to 1) build ACT from source ([master](../../tree/master) for a rel
 ACT supports generation of bindings or implementation stubs for C++, C, Pascal, Golang, NodeJS and Python3. However, not all features of the IDL are yet supported by the individual binding or implementation language:
 
 #### Feature Matrix: Bindings
-| Binding         |         Status                                             | Operating Systems |   class   |  scalar type  |     struct    |  enumeration  |     string    | basicarray | structarray | Callbacks | Error Message Propagation | Injection |
-|:---------------:|:----------------------------------------------------------:|:-----------------:|:---------:|:-------------:|:-------------:|:-------------:|:-------------:|:----------:|:-----------:|:---------:|:---------:|:---------:|
-| C++             | ![](Documentation/images/Tick.png) mature                  | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |   in,out   |    in,out   |    in     |         +        | + |
-| C++ Dynamic     | ![](Documentation/images/Tick.png) mature                  | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |   in,out   |    in,out   |    in     |         +        | + |
-| C               | ![](Documentation/images/Tick.png) mature                  | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |   in,out   |    in,out   |    in     |         +        | - |
-| C Dynamic       | ![](Documentation/images/Tick.png) mature                  | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |   in,out   |    in,out   |    in     |         +        | - |
-| Pascal          | ![](Documentation/images/Tick.png) mature                  | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |   in,out   |    in,out   |    in     |         +        | + |
-| Python3         | ![](Documentation/images/Tick.png) complete (but not very pythonic) | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |   in,out   |    in,out   |    in     |         +        | + |
-| Golang         | ![](Documentation/images/Tick.png) mature                  | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |   in,out   |    in,out   |    in     |         +        | + |
-| NodeJS          | ![](Documentation/images/O.png) partial support            | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |     ?    |      ?      |     -     |         +        | - |
-| C#              | ![](Documentation/images/O.png) experimental               | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |      -     |      -      |     -     |         +        | - |
-| Java            | ![](Documentation/images/Tick.png) experimental            | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |    in,out  |    in,out   |    in     |         +        | + |
-| PHP             | ![](Documentation/images/X.png) not implemented            | Win, Linux, MacOS | -         | -             |       -       |       -       |      -        |       -    |      -      |     -     |         -        | - |
+| Binding         |         Status                                             | Operating Systems |   class   |  scalar type  |     struct    |  enumeration  |     string    | basicarray | structarray | Callbacks | Error Message Propagation | Injection | API Documentation |
+|:---------------:|:----------------------------------------------------------:|:-----------------:|:---------:|:-------------:|:-------------:|:-------------:|:-------------:|:----------:|:-----------:|:---------:|:---------:|:---------:|:---------:|
+| C++             | ![](Documentation/images/Tick.png) mature                  | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |   in,out   |    in,out   |    in     |         +        | + | + |
+| C++ Dynamic     | ![](Documentation/images/Tick.png) mature                  | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |   in,out   |    in,out   |    in     |         +        | + | + |
+| C               | ![](Documentation/images/Tick.png) mature                  | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |   in,out   |    in,out   |    in     |         +        | - | - |
+| C Dynamic       | ![](Documentation/images/Tick.png) mature                  | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |   in,out   |    in,out   |    in     |         +        | - | - |
+| Pascal          | ![](Documentation/images/Tick.png) mature                  | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |   in,out   |    in,out   |    in     |         +        | + | + |
+| Python3         | ![](Documentation/images/Tick.png) complete (but not very pythonic) | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |   in,out   |    in,out   |    in     |         +        | + | - |
+| Golang         | ![](Documentation/images/Tick.png) mature                  | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |   in,out   |    in,out   |    in     |         +        | + | - |
+| NodeJS          | ![](Documentation/images/O.png) partial support            | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |     ?    |      ?      |     -     |         +        | - | - |
+| C#              | ![](Documentation/images/O.png) experimental               | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |      -     |      -      |     -     |         +        | - | - |
+| Java            | ![](Documentation/images/Tick.png) experimental            | Win, Linux, MacOS | in,return | in,out,return | in,out,return | in,out,return | in,out,return |    in,out  |    in,out   |    in     |         +        | + | - |
+| PHP             | ![](Documentation/images/X.png) not implemented            | Win, Linux, MacOS | -         | -             |       -       |       -       |      -        |       -    |      -      |     -     |         -        | - | - |
 
 #### Feature Matrix: Implementation Stubs
 | Implementation |         Status                                        | Operating Systems |   class   |  scalar type  |     struct    |  enumeration  |     string    | basicarray | structarray | Callbacks | Journaling | Error Message Propagation | Injection |

diff --git a/Source/automaticcomponenttoolkit.go b/Source/automaticcomponenttoolkit.go
@@ -64,6 +64,7 @@ func createComponent(component ComponentDefinition, outfolderBase string, bindin
 	outputFolder := path.Join(outfolderBase, component.NameSpace+"_component")
 	outputFolderBindings := path.Join(outputFolder, "Bindings")
 	outputFolderExamples := path.Join(outputFolder, "Examples")
+	outputFolderDocumentation := path.Join(outputFolder, "Documentations")
 	outputFolderImplementations := path.Join(outputFolder, "Implementations")
 
 	if bindingsDirectoryOverride != "" {
@@ -176,6 +177,12 @@ func createComponent(component ComponentDefinition, outfolderBase string, bindin
 
 			case "Cpp":
 				{
+					outputFolderDocumentationCppImplicit := outputFolderDocumentation + "/Cpp"
+					err = os.MkdirAll(outputFolderDocumentationCppImplicit, os.ModePerm)
+					if err != nil {
+						log.Fatal(err)
+					}
+
 					outputFolderBindingCppImplicit := outputFolderBindings + "/Cpp"
 					err = os.MkdirAll(outputFolderBindingCppImplicit, os.ModePerm)
 					if err != nil {
@@ -204,7 +211,7 @@ func createComponent(component ComponentDefinition, outfolderBase string, bindin
 					}
 
 					err = BuildBindingCppImplicit(component, outputFolderBindingCppImplicit, outputFolderExampleCppImplicit,
-						indentString, binding.ClassIdentifier)
+						outputFolderDocumentationCppImplicit, indentString, binding.ClassIdentifier)
 					if err != nil {
 						return err
 					}

diff --git a/Source/buildbindingccpp.go b/Source/buildbindingccpp.go
@@ -115,7 +115,8 @@ func BuildBindingCExplicit(component ComponentDefinition, outputFolder string, o
 }
 
 // BuildBindingCppImplicit builds dynamic C++-bindings of a library's API in form of implicitly linked functions handles.
-func BuildBindingCppImplicit(component ComponentDefinition, outputFolder string, outputFolderExample string, indentString string, ClassIdentifier string) error {
+func BuildBindingCppImplicit(component ComponentDefinition, outputFolder string, outputFolderExample string, 
+	outputFolderDocumentation string, indentString string, ClassIdentifier string) error {
 	forceRecreation := false
 	ExplicitLinking := false
 
@@ -168,9 +169,17 @@ func BuildBindingCppImplicit(component ComponentDefinition, outputFolder string,
 			log.Printf("Omitting recreation of C++-example CMakeLists-file \"%s\"", CPPCMake)
 		}
 	}
+
+	err = BuildCCPPDocumentation(component, outputFolderDocumentation, ClassIdentifier)
+	if err != nil {
+		return err
+	}
+
+
 	return nil
 }
 
+
 func buildDynamicCCPPHeader(component ComponentDefinition, w LanguageWriter, NameSpace string, BaseName string,
 	headerOnly bool, useCPPTypes bool) error {
 
@@ -523,7 +532,7 @@ func buildDynamicCImplementation(component ComponentDefinition, w LanguageWriter
 	return nil
 }
 
-func writeDynamicCPPMethodDeclaration(method ComponentDefinitionMethod, w LanguageWriter, NameSpace string, ClassIdentifier string, ClassName string) error {
+func getDynamicCPPMethodParameters(method ComponentDefinitionMethod, NameSpace string, ClassIdentifier string, ClassName string) (string, string, error) {
 	parameters := ""
 	returntype := "void"
 
@@ -560,12 +569,19 @@ func writeDynamicCPPMethodDeclaration(method ComponentDefinitionMethod, w Langua
 		case "return":
 			returntype = getBindingCppParamType(param.ParamType, param.ParamClass, NameSpace, ClassIdentifier, false)
 		default:
-			return fmt.Errorf("invalid method parameter passing \"%s\" for %s.%s(%s)", param.ParamPass, ClassName, method.MethodName, param.ParamName)
+			return "", "", fmt.Errorf("invalid method parameter passing \"%s\" for %s.%s(%s)", param.ParamPass, ClassName, method.MethodName, param.ParamName)
 		}
 	}
 
-	w.Writeln("  inline %s %s(%s);", returntype, method.MethodName, parameters)
+	return parameters, returntype, nil
+}
 
+func writeDynamicCPPMethodDeclaration(method ComponentDefinitionMethod, w LanguageWriter, NameSpace string, ClassIdentifier string, ClassName string) error {
+	parameters, returntype, err := getDynamicCPPMethodParameters(method, NameSpace, ClassIdentifier, ClassName)
+	if (err!= nil) {
+		return err
+	}
+	w.Writeln("  inline %s %s(%s);", returntype, method.MethodName, parameters)
 	return nil
 }
 
@@ -967,12 +983,12 @@ func writeCPPInputVector(w LanguageWriter, NameSpace string, ClassIdentifier str
 	w.Writeln("  ")
 	w.Writeln("public:")
 	w.Writeln("  ")
-	w.Writeln("  C%sInputVector( const std::vector<T>& vec)", ClassIdentifier)
+	w.Writeln("  C%sInputVector(const std::vector<T>& vec)", ClassIdentifier)
 	w.Writeln("    : m_data( vec.data() ), m_size( vec.size() )")
 	w.Writeln("  {")
 	w.Writeln("  }")
 	w.Writeln("  ")
-	w.Writeln("  C%sInputVector( const T* in_data, size_t in_size)", ClassIdentifier)
+	w.Writeln("  C%sInputVector(const T* in_data, size_t in_size)", ClassIdentifier)
 	w.Writeln("    : m_data( in_data ), m_size(in_size )")
 	w.Writeln("  {")
 	w.Writeln("  }")
@@ -1089,6 +1105,20 @@ func getBindingCppVariableName(param ComponentDefinitionParam) string {
 }
 
 
+func getCPPInheritanceSpecifier(component ComponentDefinition, class ComponentDefinitionClass, cppClassPrefix string, ClassIdentifier string) (string, string) {
+	cppParentClassName := ""
+	inheritanceSpecifier := ""
+	if !component.isBaseClass(class) {
+		if class.ParentClass == "" {
+			cppParentClassName = cppClassPrefix + ClassIdentifier + component.Global.BaseClassName
+		} else {
+			cppParentClassName = cppClassPrefix + ClassIdentifier+ class.ParentClass
+		}
+		inheritanceSpecifier = fmt.Sprintf(": public %s ", cppParentClassName)
+	}
+	return cppParentClassName, inheritanceSpecifier
+}
+
 func buildCppHeader(component ComponentDefinition, w LanguageWriter, NameSpace string, BaseName string, ClassIdentifier string, ExplicitLinking bool) error {
 	useCPPTypes := true
 
@@ -1389,16 +1419,7 @@ func buildCppHeader(component ComponentDefinition, w LanguageWriter, NameSpace s
 		class := component.Classes[i]
 		cppClassName := cppClassPrefix + ClassIdentifier + class.ClassName
 
-		cppParentClassName := ""
-		inheritanceSpecifier := ""
-		if !component.isBaseClass(class) {
-			if class.ParentClass == "" {
-				cppParentClassName = cppClassPrefix + ClassIdentifier + component.Global.BaseClassName
-			} else {
-				cppParentClassName = cppClassPrefix + ClassIdentifier+ class.ParentClass
-			}
-			inheritanceSpecifier = fmt.Sprintf(": public %s ", cppParentClassName)
-		}
+		cppParentClassName, inheritanceSpecifier := getCPPInheritanceSpecifier(component, class, cppClassPrefix, ClassIdentifier)
 
 		w.Writeln("  ")
 		w.Writeln("/*************************************************************************************************************************")
@@ -1630,7 +1651,7 @@ func BuildBindingCppExplicit(component ComponentDefinition, outputFolder string,
 }
 
 
-func buildDynamicCppExample(componentdefinition ComponentDefinition, w LanguageWriter, outputFolder string, ClassIdentifier string, ExplicitLinking bool) error {
+func buildDynamicCppExample(componentdefinition ComponentDefinition, w LanguageWriter, outputFolder string, ClassIdentifier string, ExplicitLinking bool) {
 	NameSpace := componentdefinition.NameSpace
 	BaseName := componentdefinition.BaseName
 
@@ -1679,8 +1700,6 @@ func buildDynamicCppExample(componentdefinition ComponentDefinition, w LanguageW
 	w.Writeln("  return 0;")
 	w.Writeln("}")
 	w.Writeln("")
-
-	return nil
 }
 
 func buildCppDynamicExampleCMake(componentdefinition ComponentDefinition, w LanguageWriter, outputFolder string, outputFolderExample string, ExplicitLinking bool) error {