elastic / elastic/docs-tools

VPR: growing list of gsubs creates risk

Open
#60 0 comments 1 reaction 0 assignees View on GitHub
Dominant language
Ruby
Stars
4
Forks
12
PR merge metrics
No merged PRs in 30d

Description

In the versioned plugin reference (VPR) we generate docs for every version of every plugin, but unfortunately some plugins have broken docs in certain released versions that if left unfixed would break our docs build. We cannot modify the source of released plugins, so to address this we have [a growing list of gsub expressions](https://github.com/elastic/docs-tools/blob/9ddef7cf890bb3b9bb747135cba175d97e638720/versioned_plugins.rb#L312-L330) that are applied to find the offending substring and replace it with something valid.

These gsub replacements are applied to _all_ plugins, and can end up with unintended side-effects (like the helpful replacement of `[source]` with `[source,shell]` for improved syntax highlighting also mucking up ECS docs referencing the `[source]` field [#59]).

It would be nice to be able to constrain a fix to a particular plugin, or even to specific versions of a plugin. Bonus points for being able to specify in config instead of in code.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.