Questions about doc-generator subsets

[kriegeraa]

Hey,

I am using the doc-generator to create a redfish specification that reflects our concrete implementation. So I use the subset functionality for it, pretty cool! Thanks for releasing that.

I got pretty far, but there are still some things I seem not to be able to do via the configs (at least not without changing the generator/formatter). Could you perhaps confirm that the following points are not possible right now? (And if thats actually not the case, please let me know how to do it.) I also add examples to show how I guessed it should work.

1. Customize "Common Objects" section

Let's say I want to have only a handful of common objects to show there (e.g. IPv4Address, Status) and I also want only a subset of their properties to show (e.g. no Oem property) and limit the supported values of some properties (State with only three possible values).

"IPv4Address": {
	"Properties": {
		"Oem": {"Include": false}
	}
},
"Status": {
	"Properties": {
		"Conditions ": {"Include": false},
		"HealthRollup ": {"Include": false},
		"Oem ": {"Include": false},
		"State": {"SupportedValues": [ "Disabled", "Enabled", "Updating"]}
	}
}

2. Edit list of Resource Collection URIs

Some resource collection URIs are not available in our implementation, which is why I want to remove them from the list. E.g. I want to overwrite them like this:

"CertificateCollection" :{
	"URIs": [
		"/​redfish/​v1/​AccountService/​Accounts/​{ManagerAccountId}/​Certificates",
		"/​redfish/​v1/​Managers/​{ManagerId}/​NetworkProtocol/​HTTPS/​Certificates"
	]
},
"CircuitCollection" :{
	"URIs": [
		"/​redfish/​v1/​PowerEquipment/​PowerShelves/​{PowerDistributionId}/​Branches",
		"/​redfish/​v1/​PowerEquipment/​PowerShelves/​{PowerDistributionId}/​Mains"
	]
},

3. Edit Action properties

Let's say I want to edit the parameters of CollectDiagnosticData action, limit the options for DiagnosticDataType and remove the property OEMDiagnosticDataType.

"LogService" :{
	"Actions": {
		"CollectDiagnosticData": {
			"Parameters": {
				"DiagnosticDataType": {"SupportedValues": ["Manager"]},
				"OEMDiagnosticDataType": {"Include": false}
			}
		}
	}
}

4. Edit a property that is part of two actions

E.g. there is ResetType which is a property of action Reset and ResetToDefaults. I want to remove two properties from each

"Manager" :{
	"Actions": {
		"Reset": {
			"Parameters": {
				"ForceOff": {"Include": false},
				"ForceOn": {"Include": false}
			}
		},
		"ResetToDefaults": {
			"PreserveNetwork": {"Include": false},
			"PreserveNetworkAndUsers": {"Include": false}
		}
	}
}

5. Remove properties from elements inside an array property

Let's say you want to only use DataSourceUri and Reading inside the elements of the RailCurrentAmps property.

With non-array properties I can do it like in the example, for array properties it does not work.

"PowerSupplyMetrics" :{
	"RailCurrentAmps": {
		"Properties": {
			"DataSourceUri": {},
			"Reading": {}
		}
	}
}

[jautor]

1. Customize "Common Objects" section

Let's say I want to have only a handful of common objects to show there (e.g. IPv4Address, Status) and I also want only a subset of their properties to show (e.g. no Oem property) and limit the supported values of some properties (State with only three possible values).

The "Common Object" section is still generated from the schema contents. Can you try adding an entry for the "Resource" schema (or wherever else your common objects are actually defined) and filter out properties/values you don't want to appear - and see if that gets reflected in the common objects section. I hope the schemas are all ingested and filtered prior to the creation of that special section.

If not, you can probably fake out the generator by listing those as common properties, but never actually placing a [insert_common_objects] directive in your document. Then create a custom schema file for your common objects (subset) and use the #include_fragment command to insert a table that you'd call your "Common Objects".

Those are used in DSP2046 to generate the example tables such as the "Payload Annotations":

#include_fragment ./docs/DSP2046/CommonPropertySchema.json#/definitions/PropertyAnnotations/properties

2. Edit list of Resource Collection URIs

Some resource collection URIs are not available in our implementation, which is why I want to remove them from the list. E.g. I want to overwrite them like this:

This is missing functionality that needs to be added for the subset mode. I've opened an issue for this. The only workaround currently would be to edit the schema files to remove the unwanted URIs.

3. Edit Action properties

Let's say I want to edit the parameters of CollectDiagnosticData action, limit the options for DiagnosticDataType and remove the property OEMDiagnosticDataType.

Yes, you can remove entire parameters or provide a subset of the allowable values.

"LogService" :{
	"Actions": {
		"CollectDiagnosticData": {
			"Parameters": {
				"DiagnosticDataType": {"SupportedValues": ["Manager"]},
				"OEMDiagnosticDataType": {"Include": false}
			}
		}
	}
}

You need to list the Action name as it appears in schema, in your example, that should be #LogService.CollectDiagnosticData.

4. Edit a property that is part of two actions

E.g. there is ResetType which is a property of action Reset and ResetToDefaults. I want to remove two properties from each

This should work but if they are using a common definition it may depend on the order these are processed. As above, change that action name to #Manager.Reset and see if that works...

5. Remove properties from elements inside an array property

Let's say you want to only use DataSourceUri and Reading inside the elements of the RailCurrentAmps property.

With non-array properties I can do it like in the example, for array properties it does not work.

"PowerSupplyMetrics" :{
	"RailCurrentAmps": {
		"Properties": {
			"DataSourceUri": {},
			"Reading": {}
		}
	}
}

That's a bug, then - but I would like to know if that happens on other object-array properties - this one in particular is an "excerpt" which may be a special case. We need to try it on a non-excerpt array object - but please enter a separate issue on that bug...

Glad you're getting use out of the tool and the subset mode - this is why it was created as we saw a need for API documentation tailored to an implementation.

Jeff

[kriegeraa]

Hi Jeff,

thank you for your fast reply, appreciate the help!


1. Customize "Common Objects" section

Can you try adding an entry for the "Resource" schema (or wherever else your common objects are actually defined) and filter out properties/values you don't want to appear

I tried that. but it does not seem to do anything.

As soon as you add a subset config, all the common objects will disappear. Thus my example above (just adding Status to the subset "IncludeSchemas"). But that will actually result in a TypeError: 'NoneType' object is not subscriptable, probably because there is no Status schema file (because it is included in Resource)? I was simply modifying the get_prop_subset function to catch the error and return None in that case, and that actually then lists (for example) Status under common objects. But I still cannot change anything about the properties that appear under the common objects.

The #include_fragment seems like a good workaround for now, I will try that. Thanks.


2. Edit list of Resource Collection URIs

This is missing functionality that needs to be added for the subset mode.

My workaround for now was to overwrite the URIs with the syntax you see in my example above. For this I just had to make this quick change in the generate_output function.

            if profile.get('URIs'):
                uris = profile['URIs']
            else:
                uris = details['uris']

to

            if subset.get('URIs'):
                uris = subset['URIs']
            elif profile.get('URIs'):
                uris = profile['URIs']
            else:
                uris = details['uris']

3. Edit Action properties

You need to list the Action name as it appears in schema, in your example, that should be #LogService.CollectDiagnosticData.

Indeed that works. I just wonder, do you know why for the CertificateService it seems to be the opposite?
For example this works (just using GenerateCSR):

"CertificateService" :{
	"Actions": {
		"GenerateCSR": {
			"Parameters": {
				"KeyUsage": {"SupportedValues": ["ClientAuthentication"]}
			}
		}
	}
}

and this does actually not work (using #CertificateService.GenerateCSR)

"CertificateService" :{
	"Actions": {
		"#CertificateService.GenerateCSR": {
			"Parameters": {
				"KeyUsage": {"SupportedValues": ["ClientAuthentication"]}
			}
		}
	}
}

4. Edit a property that is part of two actions

change that action name to #Manager.Reset and see if that works...

Does not seem to change anything. I also tried changing the order of the actions, but that had no effect either. Any other idea? Or should we consider this a bug too then?

5. Remove properties from elements inside an array property

if that happens on other object-array properties

Indeed, seems only the excerpts don't work. Event/Events for example is an array element that does change. I created a new issue #434