Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(tools): Allow to markdown includes for sections #12075

Merged
merged 5 commits into from
Oct 24, 2022

Conversation

srebhan
Copy link
Member

@srebhan srebhan commented Oct 20, 2022

related to #11691
fixes: #9065

This PR extends the readme_config_includer in two ways. First, it allows global includes relative to the Telegraf project root by specifying an absolute path (e.g. /docs/bla.md).
Additionally, the tool now also allows to replace sections of the document by providing include(s) at the header level. For example in the following README:

Some text
[...]
## My included part <!-- @/docs/include/replacement.md -->

more text, code, also
multi-line text

or 
additional paragraphs, etc as well as

### Subsections

as long as they have a deeper 
level (more hashes) are replaces until

## A heading on the same level

occures.

everything after ## My included part <!-- @/docs/include/replacement.md --> and before ## A heading on the same level is replaced by the content of /docs/include/replacement.md. The result is stable as long as the included file will not insert headings on a lower or equal level compared to the include heading.

@telegraf-tiger telegraf-tiger bot added the feat Improvement on an existing feature such as adding a new setting/mode to an existing plugin label Oct 20, 2022
@srebhan srebhan requested a review from powersj October 20, 2022 17:37
Copy link
Contributor

@powersj powersj left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is exactly what we wanted! The restriction of:

The result is stable as long as the included file will not insert
headings on a lower or equal level compared to the include heading.

Is totally fine way of limiting what this replaces and puts in as well.

Thank you!

@powersj powersj added the ready for final review This pull request has been reviewed and/or tested by multiple users and is ready for a final review. label Oct 21, 2022
@powersj
Copy link
Contributor

powersj commented Oct 24, 2022

I'm ready to merge this, but there are two lint errors we will want to clean up:

/github/workspace/docs/includes/plugin_config.md:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "In addition to the plugin-spec..."]
/github/workspace/docs/includes/plugin_config.md:6:50 MD047/single-trailing-newline Files should end with a single newline character

The first should be ignored especially if we add future of these types of markdown docs

The second you should fix. Will this add an extra new line between sections?

@telegraf-tiger
Copy link
Contributor

@srebhan srebhan merged commit b76b53d into influxdata:master Oct 24, 2022
dba-leshop pushed a commit to dba-leshop/telegraf that referenced this pull request Oct 30, 2022
popey pushed a commit that referenced this pull request Nov 2, 2022
@srebhan srebhan deleted the doc_embedding_path branch November 7, 2022 11:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feat Improvement on an existing feature such as adding a new setting/mode to an existing plugin ready for final review This pull request has been reviewed and/or tested by multiple users and is ready for a final review.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add default configuration params to plugin docs
3 participants