[FR] Folder-level READMEs for variables

[fedderw]

I think folder-level README explanations of variable calculations would make it easier to debug, and for a new set of eyes to come in and aid in debugging or extending.

I found myself wanting this a lot and trying to hack it together with Obsidian extensions.

It's one more hassle to maintain, but something like markdown-magic could make it easier.

• Automatically keep markdown files up to date from local or remote code sources
• Transform markdown content with custom transform functions
• Render markdown with any template engine
• Automatically generate a table of contents
• ... etc

The comments markdown magic uses are hidden in markdown and when viewed as HTML.

This README.md is generated with markdown-magic view the raw file to see how.

Video demo • Example Repo

[MaxGhenis]

Interesting tool, thanks Will. So far we've used the documentation notebooks for written explanation of variables (using Markdown), but we could probably formalize this process, potentially with markdown files for each variable. Need to find a balance between structured fields that go as Python object attributes for variables and yaml values for parameters, and longer written content that doesn't fit in there (and also is more convenient to write in markdown).

Moving this to a discussion since we need more research to figure out the design and whether to act on it.