[docs] Fix netflow field docs by removing duplicate topic #16784

dedemorton · 2020-03-04T02:32:36Z

Right now we have repeated titles in the documentation because we don't want to duplicate the field reference added by the netflow module and the netflow input.

I'm wondering if it makes sense to add a nofields field to the yml file for those rare occasions when we truly don't want to document the fields.

Here's my attempt at modifying our doc gen script. Someone on the dev team should verify in case there's an impact I don't understand.

libbeat/scripts/generate_fields_docs.py

urso · 2020-03-04T11:30:24Z

I didn't check, but I wonder if it would be better to filter on presence of 'fields'? This way we just have to not use 'fields' in the YAML, instead of introducing another special 'indicator' field.

dedemorton · 2020-03-04T18:37:51Z

@urso Regarding your comment:

I didn't check, but I wonder if it would be better to filter on presence of 'fields'? This way we just have to not use 'fields' in the YAML, instead of introducing another special 'indicator' field.

I did consider doing that, but it goes contrary to what we've said we want to do. Right now, we require contributors to provide fields because we want to enforce the requirement for documentation. This works 99% of the time and forces contributors to document something. The only exception is when we have something like a module that duplicates the same fields as an input. In that case, we don't want to document the exported fields twice because it's confusing to users, so we need a way to indicate that no fields are OK.

Having an explicit field that says "We don't want to generate field documentation for this" seems like a good way to get around the problem, simplify the logic, and make it clear that the fields are intentionally missing. I'm not really a programmer, though, so I'm sure you can come up with something better. :-)

WDYT?

urso · 2020-03-05T11:43:15Z

For my understanding. This means that 'fields' must always be present and never must be empty? In this case, yeah nofields would be a good indicator that 'fields' is allowed to be empty or missing.

dedemorton · 2020-03-05T19:00:29Z

This means that 'fields' must always be present and never must be empty?

Yes, that was the idea initially, but of course, it's up to us to decide whether we want to enforce the requirement. I will say that relying on PR reviews to identify missing docs has not worked very well for us so far. :-P

urso · 2020-03-05T20:01:34Z

I see. In this case adding nofields: would be the right choice. I'd rather have CI complain if docs are not complete.

Alternatively we could also use fields: none as indicator that we have no fields. WDYT?

dedemorton · 2020-03-11T00:11:54Z

Alternatively we could also use fields: none as indicator that we have no fields. WDYT?

Hm....thinking more about this...technically there are fields, we just don't want to document them twice. We want to skip the step that generates the docs. So maybe calling this field something like skipdocs would make more sense.

Not sure about setting fields to none because fields expects an object. I think I'd have to change more than just the one docgen file.

dedemorton · 2020-04-15T19:24:01Z

@urso I got side tracked on this one. WDYT about my proposal (adding a new field and calling it something like skipdocs to be more descriptive)?

urso · 2020-04-20T14:42:16Z

+1 on skipdocs.

libbeat/scripts/generate_fields_docs.py

elasticmachine · 2020-04-29T19:33:50Z

💔 Build Failed

Expand to view the summary

Build stats

Build Cause: [Pull request [docs] Fix netflow field docs by removing duplicate topic #16784 updated]
Start Time: 2020-04-29T18:23:05.404+0000
Duration: 71 min 36 sec (4235863)
Commit: 2cce871

Test stats 🧪

Test	Results
Failed	157
Passed	7395
Skipped	1223
Total	8775