Strange rendering of executor plugin API reference doc

[dinever]

Looks like the multi-line comments got rendered in multiple table rows, making the API docs unreadable: https://argoproj.github.io/argo-workflows/executor_swagger/

swagger.yml:

argo-workflows/pkg/plugins/executor/swagger.yml

Lines 11 to 19 in 774bf47

	properties:
	fsType:
	description: |-
	Filesystem type of the volume that you want to mount.
	Tip: Ensure that the filesystem type is supported by the host operating system.
	Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
	More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore
	TODO: how do we prevent errors in the filesystem from compromising the machine
	+optional

executor_swagger.md:

argo-workflows/docs/executor_swagger.md

Lines 82 to 90 in 774bf47

	| Name | Type | Go type | Required | Default | Description | Example |
	|------|------|---------|:--------:| ------- |-------------|---------|
	| fsType | string| `string` | | | Filesystem type of the volume that you want to mount.
	Tip: Ensure that the filesystem type is supported by the host operating system.
	Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
	More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore
	TODO: how do we prevent errors in the filesystem from compromising the machine
	+optional | |
	| partition | int32 (formatted integer)| `int32` | | | The partition in the volume that you want to mount.

Not sure what's the best workaround for this.

Maybe instead of populating the entire Workflow spec on this page, we could just link to the Field Reference page? https://argoproj.github.io/argo-workflows/fields/

[alexec]

This must be a bug when running env SWAGGER_GENERATE_EXTENSION=false swagger generate markdown -f swagger.yml --output ../../../docs/executor_swagger.md

[tczhao]

When go-swagger/go-swagger@36e5a26 release,
it should resolve this issue

[agilgur5]

go-swagger/go-swagger@36e5a26

For backlinking, go-swagger/go-swagger#3044 is the PR, which closed the upstream issue that Alex filed: go-swagger/go-swagger#2700

But yea go-swagger has needed a new release for a bit: go-swagger/go-swagger#3070