Feature request: Create markdown documents

[adamrtalbot]

Having used terraform-docs recently, I think there's some value in automatically generating some documentation from the schema file for a human to read, e.g. onto a README.md

A rough plan could be:

1. Make sure you have a target markdown file (default README.md)
2. Add some configuration blocks for configuring how nf-schema should write this content (e.g. terraform-docs inspiration)
3. Add placeholders for different fields, e.g. {{ params }}, {{ .assets.schema.${id} }}, {{ profiles }}, {{ outputs }}
4. When running the nf-schema a plugin command nf-schema will substitute in the fields from the schema and place them into the markdown.
5. This could be ran as a pre-commit hook or CI/CD to auto generate, simple but effective docs.

This doesn't have to be an nf-schema feature, but that seems like the most obvious place since it is already parsing the schema file etc.

[nvnieuwk]

I really really love this idea! I think this could be a nice feature! I'm also not 100% sure it fits in this plugin (I would need to think about it).

We also do something similar already with the nf-core website (not entirely the same of course, but maybe this could benefit from the code already written there)

[adamrtalbot]

I wasn't sure about adding it to nf-schema but, keeping it in the same repo and making sure it's sharing the logic might prevent deviations appearing.

Perhaps as a POC we can write a separate tool to parse the schema file and/or some Nextflow logic. Hmmm now I think about it, we might be able to write it in Groovy and import Nextflow + nf-schema...?

[nvnieuwk]

Yes this might be better as a standalone tool since you don't want it to run with every pipeline run, but only when you update your documentation.

Deviations won't be a big problem here as this would be closely linked to JSON schema specs anyways. With the release of the nextflow schema coming soon this should be even easier.

[adamrtalbot]

Okey dokey. In that case, is it practical to import nf-schema as a library?

This seems like a good hackathon project!

[nvnieuwk]

I've never tried it and I'm not sure how possible it is 😁. I'd be curious to see what you can come up with!

[awgymer]

I'm not sure how this is really coupled with nf-schema?

profiles and outputs sound like things from the actual pipeline, which nf-schema neither knows about or parses?

For markdown generation of params we already have this in nf-core pipelines schema docs.

I like the idea of a more customised templated README but it feels like something which should be more based in nextflow or nf-core and provide broader functionality than simply params documentation.

Things like profiles and outputs would be great to parse out of the pipeline code but that syntax handling already exists in nextflow and something like nextflow inspect feels like a more natural home for this?

[adamrtalbot]

profiles and outputs sound like things from the actual pipeline, which nf-schema neither knows about or parses?

Yeah I got ahead of myself there 😆 the nf-schema component is just for parameters and schema related stuff.

For markdown generation of params we already have this in nf-core pipelines schema docs.

I didn't know this existed! Still, I really dislike the "well it exists in nf-core so let's not bother", nf-core represents a very small fraction of Nextflow users and anything useful for the wider Nextflow community should exist in the wider Nextflow community. nf-schema is a great example of that!

something like nextflow inspect feels like a more natural home for this?

I think so, although I'm not sure whether putting it in the core codebase is a good idea.

Based on some further discussion on Slack and here, I think that:

1. It's a good idea
2. It's optional, should be lightweight and easy (e.g. small install, sub 0.5 second runtime)
3. It makes sense to import Nextflow and/or nf-schema components to keep it consistent with those tools
4. It's not 100% clear where it should live, but given it's a bonus feature, I'm gravitating towards it being standalone (like terraform-docs)

I haven't discussed the user features, which are the most important thing 😅 enough nerding, more UX.

[awgymer]

It makes sense to import Nextflow and/or nf-schema components to keep it consistent with those tools

For me this really depends on whether you want it to do more than params documentation. If you just want parameter/samplesheet documentation then really you don't need any nextflow or nf-schema other than their underlying meta-schemas. That's sort of the beauty of using jsonschema, we can do the extra stuff in whatever language we want.

And this is obviously highly subjective but I don't favour writing these kinds of utilities in Java/Groovy if I don't have to.

The schema docs logic from nf-core for example could likely be ported to a fairly simple single python script which would likely be both easier to use and easier to modify for the average user than some Java tool that needs recompiling to test/run.

It's not 100% clear where it should live

It feels like there has been quite a bit of expansion of scope with core nextflow (e.g. a linter in the language itself, there's no python lint or rust lint, these things are offloaded to external tools) and even now nf-schema potentially is going to be redundant with static typing and more of the functionality being ported into core nextflow, so in that sense I'm less inclined to spin up an external project which might just as quickly become redundant and/or create a situation where there are competing standards, and tend more towards pushing to get functionality into existing the landscape and only branch off if it's made emphatically clear it's not going to become part of the core product. Again the exact situation here probably depends on whether this docs generation should go beyond the jsonschema elements.

[awgymer]

Material for MkDocs is dead, as is mkdocstrings, but thinking about it more I wonder if this sort of functionality is better served being setup as plugins for similar static site generators (the official replacement for Material for MkDocs is Zensical but it doesn't yet have a public plugins/API documentation setup AFAICT) than as a standalone project which would be limited, presumably, to only supporting Nextflow code?

[adamrtalbot]

Material for MkDocs is dead, as is mkdocstrings, but thinking about it more I wonder if this sort of functionality is better served being setup as plugins for similar static site generators (the official replacement for Material for MkDocs is Zensical but it doesn't yet have a public plugins/API documentation setup AFAICT) than as a standalone project which would be limited, presumably, to only supporting Nextflow code?

You mean for general creating JSON schema -> human readable conversion? There are already a few out there, I've used this one with some success, I havent tried this one. The problem is the outputs are basically API specs, which are designed for engineers working on the code not general users. I think we can do something a bit more domain specific. Something to leave the AI vibe coding 😆

[awgymer]

I more meant that since those sorts of static site generators already do markdown templating I think they might be able to be leveraged to also handle parsing nextflow as they do e.g. Python to add content from into docs.

The packages normally can mix API generation with custom content.