How do you make those plugin docs?

[Andre601]

I'm always amazed at the design and look of the docs for the different plugins.

Looking at them, its clear for me that you're using a tool/software to generate them automatically.
My question now is, is it a selfmade one? If so, is it separately available? Also, can it be used for other stuff too?

I want to update a project of mine and would like to use such a tool to cut out repeated information or similar.

[lowlighter]

Thanks for appreciating the docs 😄 !

Documentation files are mostly auto-generated from a selfmade tool but unfortunately the code for it is a bit scattered everywhere in the codebase so it'll be hard to reuse it elsewhere, and it's tightly coupled for metrics use case anyway so I don't think it's easily reusable as it is currently... It's also not something I plan to refactor (at least in the near future).

So unfortunately it's highly improbable you'll be able to reuse the same code as metrics.
But I can explain briefly how it works though if you're interested about it, maybe it can give you ideas 🙂

---

The .github/scripts/build.mjs script is the entrypoint of all generated files (not necessarily documentation, the workflows too are auto-generated for example).

The aim of metrics documentation is to follow the "The truth is in the code" principle by having:

• code ≈ documentation
  • metadata.yml documents available options, but also serves as inputs parsing/casting/validation/defaulting code-wise
• tests ≈ examples
  • examples.yml displays examples, but also serves as integration tests in the CI/CD pipeline

While the docs from .github/readme/partials are templated with EJS, the plugins documentation tables are generated in source/app/metrics/metadata.mjs here for plugins and here for templates (but beware, it looks like weird JSX with HTML strings within JS, not the code I'm the most proud of 😅 ). Also, the code itself relies heavily on the structure of the project, everything under source/plugins is expected to be a plugin implementation and same for source/templates which expects templates definition (it uses fileglobs to iterate over existing components).

If you look at a plugin metadata.yml you'll notice that README.md is actually just a nice formatting over it. The table looks nice because they use HTML tables with rowspan/colspan and cool formatting, but the inconvenient is that it's not really markdown anymore (but it does looks nice on GitHub). The templating itself is done by replacing the content of special HTML comments (which are hidden in markdown):

<!--header-->
<!--/header-->

## ➡️ Available options

<!--options-->
<!--/options-->

... Some static documentation that can be written by plugin authors...

## ℹ️ Examples workflows

<!--examples-->
<!--/examples-->

metrics/.github/scripts/build.mjs

Lines 41 to 44 in 5100eba

	readme.content
	.replace(/(<!--header-->)[\s\S]*(<!--\/header-->)/g, `$1\n${header}\n$2`)
	.replace(/(<!--examples-->)[\s\S]*(<!--\/examples-->)/g, `$1\n${examples.map(({test, prod, ...step}) => ["```yaml", yaml.dump(step, {quotingType: '"', noCompatMode: true}), "```"].join("\n")).join("\n")}\n$2`)
	.replace(/(<!--options-->)[\s\S]*(<!--\/options-->)/g, `$1\n${options}\n$2`),

It's not a perfect solution and the implementation is kind of inconsistant (some templating done in EJS and some in JS) but at least it leverage the amount of work needed for maintenance, and the documentation is guaranteed to be up-to-date and reflects the code while the examples are supposed to be working too since they're tested on each build

[Andre601]

I kinda expected this to be the case (selfmade tool mostly included in metrics itself).

I manually recreated it myself now. Took a few hours but I feel it was worth it.

https://github.com/Andre601/Formatter-Expansion

[lowlighter]

Looks nice indeed !