Hide deprecated fields in docsgen (#2581)

## Changes

If field is deprecated
* Show deprecation message in the attributes table
* Do not show extended section of that field

## Why
We do have deprecated fields and we don't want to show them in
documentation. If deprecated field belongs to some complex type (e.g.
`pydabs` or `compute_id`) we show explicit deprecation message

## Tests
Unit test

<!-- If your PR needs to be included in the release notes for next
release,
add a separate entry in NEXT_CHANGELOG.md as part of your PR. -->

Author: ilyakuz-db

bundle/docsgen/main.go

@@ -133,6 +133,10 @@ func assignAnnotation(s *jsonschema.Schema, a annotation.Descriptor) {
 	if a.MarkdownExamples != "" {
 		s.Examples = []string{a.MarkdownExamples}
 	}
+	if a.DeprecationMessage != "" {
+		s.Deprecated = true
+		s.DeprecationMessage = a.DeprecationMessage
+	}
 }
 
 func fillTemplateVariables(s string) string {

bundle/docsgen/nodes.go

@@ -62,6 +62,10 @@ func buildNodes(s jsonschema.Schema, refs map[string]*jsonschema.Schema, ownFiel
 		}
 		visited[k] = true
 
+		if v.Deprecated {
+			continue
+		}
+
 		v = resolveRefs(v, refs)
 		node := rootNode{
 			Title:       k,
@@ -173,7 +177,7 @@ func getAttributes(props, refs map[string]*jsonschema.Schema, ownFields map[stri
 			typeString = "Any"
 		}
 		var reference string
-		if isReferenceType(v, refs, ownFields) && !circular {
+		if isReferenceType(v, refs, ownFields) && !circular && !v.Deprecated {
 			reference = prefix + "." + k
 		}
 		attributes = append(attributes, attributeNode{
@@ -190,6 +194,9 @@ func getAttributes(props, refs map[string]*jsonschema.Schema, ownFields map[stri
 }
 
 func getDescription(s *jsonschema.Schema) string {
+	if s.DeprecationMessage != "" {
+		return s.DeprecationMessage
+	}
 	if s.MarkdownDescription != "" {
 		return s.MarkdownDescription
 	}

bundle/docsgen/nodes_test.go

@@ -115,6 +115,33 @@ func TestBuildNodes_ChildExpansion(t *testing.T) {
 	}
 }
 
+func TestDeprecatedFields(t *testing.T) {
+	s := jsonschema.Schema{
+		Type: "object",
+		Properties: map[string]*jsonschema.Schema{
+			"deprecatedField": {Deprecated: true},
+			"notDeprecatedField": {
+				Properties: map[string]*jsonschema.Schema{
+					"nestedDeprecatedField": {
+						Deprecated:  true,
+						Description: "nested description",
+						Extension: jsonschema.Extension{
+							DeprecationMessage: "nested deprecation message",
+						},
+					},
+					"nestedNotDeprecatedField": {},
+				},
+			},
+		},
+	}
+	nodes := buildNodes(s, nil, nil)
+	assert.Len(t, nodes, 1)
+	assert.Equal(t, "notDeprecatedField", nodes[0].Title)
+
+	assert.Len(t, nodes[0].Attributes, 2)
+	assert.Equal(t, "nested deprecation message", nodes[0].Attributes[0].Description)
+}
+
 func strPtr(s string) *string {
 	return &s
 }