epic/OpenRA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Added enum export to documentation generation

Browse Source
This commit is contained in:
penev92
2022-06-12 21:02:25 +03:00
committed by Matthias Mailänder
parent a985452907
commit eda3dfa50f
5 changed files with 140 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
OpenRA.Mods.Common/Util.cs
View File

@@ -236,6 +236,9 @@ namespace OpenRA.Mods.Common
public static string FriendlyTypeName(Type t)
{
if (t.IsEnum)
return $"{t.Name} (enum)";
if (t.IsGenericType && t.GetGenericTypeDefinition() == typeof(HashSet<>))
return $"Set of {t.GetGenericArguments().Select(FriendlyTypeName).First()}";

29
OpenRA.Mods.Common/UtilityCommands/ExtractSequenceDocsCommand.cs
View File

@@ -48,8 +48,11 @@ namespace OpenRA.Mods.Common.UtilityCommands
static string GenerateJson(string version, IEnumerable<Type> sequenceTypes)
{
var sequenceTypesInfo = sequenceTypes.Where(x => !x.ContainsGenericParameters && !x.IsAbstract)
.Where(x => x.Name != nameof(FileNotFoundSequence)) // NOTE: This is the simplest way to exclude FileNotFoundSequence, which shouldn't be added.
var relatedEnumTypes = new HashSet<Type>();
var sequenceTypesInfo = sequenceTypes
.Where(x => !x.ContainsGenericParameters && !x.IsAbstract
&& x.Name != nameof(FileNotFoundSequence)) // NOTE: This is the simplest way to exclude FileNotFoundSequence, which shouldn't be added.
.Select(type => new
{
type.Namespace,
@@ -71,9 +74,11 @@ namespace OpenRA.Mods.Common.UtilityCommands
.GetField(nameof(SpriteSequenceField<bool>.Key))?
.GetValue(fi.GetValue(null));
var defaultValue = fi.FieldType
.GetField(nameof(SpriteSequenceField<bool>.DefaultValue))?
.GetValue(fi.GetValue(null));
var defaultValueField = fi.FieldType.GetField(nameof(SpriteSequenceField<bool>.DefaultValue));
var defaultValue = defaultValueField?.GetValue(fi.GetValue(null));
if (defaultValueField != null && defaultValueField.FieldType.IsEnum)
relatedEnumTypes.Add(defaultValueField.FieldType);
return new
{
@@ -86,10 +91,22 @@ namespace OpenRA.Mods.Common.UtilityCommands
})
});
var relatedEnums = relatedEnumTypes.Select(type => new
{
type.Namespace,
type.Name,
Values = Enum.GetNames(type).Select(x => new
{
Key = Convert.ToInt32(Enum.Parse(type, x)),
Value = x
})
});
var result = new
{
Version = version,
SpriteSequenceTypes = sequenceTypesInfo
SpriteSequenceTypes = sequenceTypesInfo,
RelatedEnums = relatedEnums
};
return JsonConvert.SerializeObject(result);

69
OpenRA.Mods.Common/UtilityCommands/ExtractTraitDocsCommand.cs
View File

@@ -46,7 +46,10 @@ namespace OpenRA.Mods.Common.UtilityCommands
static string GenerateJson(string version, IEnumerable<Type> traitTypes, ObjectCreator objectCreator)
{
var traitTypesInfo = traitTypes.Where(x => !x.ContainsGenericParameters && !x.IsAbstract)
var relatedEnumTypes = new HashSet<Type>();
var traitTypesInfo = traitTypes
.Where(x => !x.ContainsGenericParameters && !x.IsAbstract)
.Select(type => new
{
type.Namespace,
@@ -59,38 +62,56 @@ namespace OpenRA.Mods.Common.UtilityCommands
.Where(y => y != type.Name && y != $"{type.Name}Info" && y != "Object" && y != "TraitInfo`1"), // HACK: This is the simplest way to exclude TraitInfo<T>, which doesn't serialize well.
Properties = FieldLoader.GetTypeLoadInfo(type)
.Where(fi => fi.Field.IsPublic && fi.Field.IsInitOnly && !fi.Field.IsStatic)
.Select(fi => new
.Select(fi =>
{
PropertyName = fi.YamlName,
DefaultValue = FieldSaver.SaveField(objectCreator.CreateBasic(type), fi.Field.Name).Value.Value,
InternalType = Util.InternalTypeName(fi.Field.FieldType),
UserFriendlyType = Util.FriendlyTypeName(fi.Field.FieldType),
Description = string.Join(" ", fi.Field.GetCustomAttributes<DescAttribute>(true).SelectMany(d => d.Lines)),
OtherAttributes = fi.Field.CustomAttributes
.Where(a => a.AttributeType.Name != nameof(DescAttribute) && a.AttributeType.Name != nameof(FieldLoader.LoadUsingAttribute))
.Select(a =>
{
var name = a.AttributeType.Name;
name = name.EndsWith("Attribute") ? name.Substring(0, name.Length - 9) : name;
if (fi.Field.FieldType.IsEnum)
relatedEnumTypes.Add(fi.Field.FieldType);
return new
return new
{
PropertyName = fi.YamlName,
DefaultValue = FieldSaver.SaveField(objectCreator.CreateBasic(type), fi.Field.Name).Value.Value,
InternalType = Util.InternalTypeName(fi.Field.FieldType),
UserFriendlyType = Util.FriendlyTypeName(fi.Field.FieldType),
Description = string.Join(" ", fi.Field.GetCustomAttributes<DescAttribute>(true).SelectMany(d => d.Lines)),
OtherAttributes = fi.Field.CustomAttributes
.Where(a => a.AttributeType.Name != nameof(DescAttribute) && a.AttributeType.Name != nameof(FieldLoader.LoadUsingAttribute))
.Select(a =>
{
Name = name,
Parameters = a.Constructor.GetParameters()
.Select(pi => new
{
pi.Name,
Value = Util.GetAttributeParameterValue(a.ConstructorArguments[pi.Position])
})
};
})
var name = a.AttributeType.Name;
name = name.EndsWith("Attribute") ? name.Substring(0, name.Length - 9) : name;
return new
{
Name = name,
Parameters = a.Constructor.GetParameters()
.Select(pi => new
{
pi.Name,
Value = Util.GetAttributeParameterValue(a.ConstructorArguments[pi.Position])
})
};
})
};
})
});
var relatedEnums = relatedEnumTypes.Select(type => new
{
type.Namespace,
type.Name,
Values = Enum.GetNames(type).Select(x => new
{
Key = Convert.ToInt32(Enum.Parse(type, x)),
Value = x
})
});
var result = new
{
Version = version,
TraitInfos = traitTypesInfo
TraitInfos = traitTypesInfo,
RelatedEnums = relatedEnums
};
return JsonConvert.SerializeObject(result);

69
OpenRA.Mods.Common/UtilityCommands/ExtractWeaponDocsCommand.cs
View File

@@ -51,7 +51,10 @@ namespace OpenRA.Mods.Common.UtilityCommands
static string GenerateJson(string version, IEnumerable<Type> weaponTypes, ObjectCreator objectCreator)
{
var weaponTypesInfo = weaponTypes.Where(x => !x.ContainsGenericParameters && !x.IsAbstract)
var relatedEnumTypes = new HashSet<Type>();
var weaponTypesInfo = weaponTypes
.Where(x => !x.ContainsGenericParameters && !x.IsAbstract)
.Select(type => new
{
type.Namespace,
@@ -62,38 +65,56 @@ namespace OpenRA.Mods.Common.UtilityCommands
.Where(y => y != type.Name && y != $"{type.Name}Info" && y != "Object"),
Properties = FieldLoader.GetTypeLoadInfo(type)
.Where(fi => fi.Field.IsPublic && fi.Field.IsInitOnly && !fi.Field.IsStatic)
.Select(fi => new
.Select(fi =>
{
PropertyName = fi.YamlName,
DefaultValue = FieldSaver.SaveField(objectCreator.CreateBasic(type), fi.Field.Name).Value.Value,
InternalType = Util.InternalTypeName(fi.Field.FieldType),
UserFriendlyType = Util.FriendlyTypeName(fi.Field.FieldType),
Description = string.Join(" ", fi.Field.GetCustomAttributes<DescAttribute>(true).SelectMany(d => d.Lines)),
OtherAttributes = fi.Field.CustomAttributes
.Where(a => a.AttributeType.Name != nameof(DescAttribute) && a.AttributeType.Name != nameof(FieldLoader.LoadUsingAttribute))
.Select(a =>
{
var name = a.AttributeType.Name;
name = name.EndsWith("Attribute") ? name.Substring(0, name.Length - 9) : name;
if (fi.Field.FieldType.IsEnum)
relatedEnumTypes.Add(fi.Field.FieldType);
return new
return new
{
PropertyName = fi.YamlName,
DefaultValue = FieldSaver.SaveField(objectCreator.CreateBasic(type), fi.Field.Name).Value.Value,
InternalType = Util.InternalTypeName(fi.Field.FieldType),
UserFriendlyType = Util.FriendlyTypeName(fi.Field.FieldType),
Description = string.Join(" ", fi.Field.GetCustomAttributes<DescAttribute>(true).SelectMany(d => d.Lines)),
OtherAttributes = fi.Field.CustomAttributes
.Where(a => a.AttributeType.Name != nameof(DescAttribute) && a.AttributeType.Name != nameof(FieldLoader.LoadUsingAttribute))
.Select(a =>
{
Name = name,
Parameters = a.Constructor.GetParameters()
.Select(pi => new
{
pi.Name,
Value = Util.GetAttributeParameterValue(a.ConstructorArguments[pi.Position])
})
};
})
var name = a.AttributeType.Name;
name = name.EndsWith("Attribute") ? name.Substring(0, name.Length - 9) : name;
return new
{
Name = name,
Parameters = a.Constructor.GetParameters()
.Select(pi => new
{
pi.Name,
Value = Util.GetAttributeParameterValue(a.ConstructorArguments[pi.Position])
})
};
})
};
})
});
var relatedEnums = relatedEnumTypes.Select(type => new
{
type.Namespace,
type.Name,
Values = Enum.GetNames(type).Select(x => new
{
Key = Convert.ToInt32(Enum.Parse(type, x)),
Value = x
})
});
var result = new
{
Version = version,
WeaponTypes = weaponTypesInfo
WeaponTypes = weaponTypesInfo,
RelatedEnums = relatedEnums
};
return JsonConvert.SerializeObject(result);

29
packaging/format-docs.py
View File

@@ -26,7 +26,8 @@ def is_known_type(typeName, types):
result = [t for t in types if name == t["Name"]]
return len(result) > 0
def format_docs(version, collectionName, types):
def format_docs(version, collectionName, types, relatedEnums):
typesByNamespace = OrderedDict()
for currentType in types:
if currentType["Namespace"] in typesByNamespace:
@@ -34,6 +35,9 @@ def format_docs(version, collectionName, types):
else:
typesByNamespace[currentType["Namespace"]] = [currentType]
# Map the `relatedEnums` collection to a list of strings.
enumNames = [enum['Name'] for enum in relatedEnums]
explanation = ""
if collectionName == "TraitInfos":
explanation = "all traits with their properties and their default values plus developer commentary"
@@ -46,6 +50,7 @@ def format_docs(version, collectionName, types):
"Please do not edit it directly, but instead add new `[Desc(\"String\")]` tags to the source code.\n")
print(f"Listed below are {explanation}.")
print(f"Related types with their possible values are listed [at the bottom](#related-value-types-enums).")
for namespace in typesByNamespace:
print(f'\n## {namespace}')
@@ -70,6 +75,13 @@ def format_docs(version, collectionName, types):
print(f'| -------- | ------------- | ---- | ----------- |')
for prop in currentType["Properties"]:
# Use the user-friendly type name unless we're certain this is a known enum,
# in which case get a link to the enum's definition.
typeName = prop["UserFriendlyType"]
if prop["InternalType"] in enumNames:
typeName = format_type_name(prop["InternalType"], True)
if "OtherAttributes" in prop:
attributes = []
for attribute in prop["OtherAttributes"]:
@@ -81,14 +93,21 @@ def format_docs(version, collectionName, types):
elif 'Require' in attributes:
defaultValue = '*(required)*'
print(f'| {prop["PropertyName"]} | {defaultValue} | {prop["UserFriendlyType"]} | {prop["Description"]} |')
print(f'| {prop["PropertyName"]} | {defaultValue} | {typeName} | {prop["Description"]} |')
else:
print(f'| {prop["PropertyName"]} | {prop["DefaultValue"] or ""} | {prop["UserFriendlyType"]} | {prop["Description"]} |')
print(f'| {prop["PropertyName"]} | {prop["DefaultValue"] or ""} | {typeName} | {prop["Description"]} |')
if len(relatedEnums) > 0:
print('\n# Related value types (enums):\n')
for relatedEnum in relatedEnums:
values = [f"`{value['Value']}`" for value in relatedEnum["Values"]]
print(f"### {relatedEnum['Name']}")
print(f"Possible values: {', '.join(values)}\n")
if __name__ == "__main__":
input_stream = io.TextIOWrapper(sys.stdin.buffer, encoding='utf-8-sig')
jsonInfo = json.load(input_stream)
keys = list(jsonInfo)
if len(keys) == 2 and keys[0] == 'Version':
format_docs(jsonInfo[keys[0]], keys[1], jsonInfo[keys[1]])
if len(keys) == 3 and keys[0] == 'Version':
format_docs(jsonInfo[keys[0]], keys[1], jsonInfo[keys[1]], jsonInfo[keys[2]])