Merge branch 'readme-concise-docs'

Author: ewels

README.md

@@ -11,7 +11,7 @@
 
 **[Full documentation →](https://ewels.github.io/nf-docs)**
 
-Choose from 3 different output formats:
+Choose from 4 different output formats:
 
 </div>
 
@@ -23,7 +23,7 @@ Choose from 3 different output formats:
 </td>
 <td width="33%">
 <h3 align="center">Markdown</h3>
-<ul><li>Multiple files by section</li><li>Perfect for static site generators</li></ul><hr>
+<ul><li>Multiple files or tables by section</li><li>Perfect for static site generators</li></ul><hr>
 </td>
 <td width="33%">
 <h3 align="center">JSON / YAML</h3>

docs/examples.md

@@ -2,10 +2,10 @@
 
 Generated documentation for real-world Nextflow pipelines.
 
-| Pipeline        | Description                                  | HTML                                        | Markdown                                               | JSON                                                    |
-| --------------- | -------------------------------------------- | ------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------- |
-| hello           | Nextflow hello-world pipeline                | [HTML](examples/hello/index.html)           | [Markdown](examples/hello/markdown/index.md)           | [JSON](examples/hello/json/pipeline-api.json)           |
-| rnaseq-nf       | Simple RNA-seq pipeline                      | [HTML](examples/rnaseq-nf/index.html)       | [Markdown](examples/rnaseq-nf/markdown/index.md)       | [JSON](examples/rnaseq-nf/json/pipeline-api.json)       |
-| rnavar          | nf-core/rnavar — RNA variant calling         | [HTML](examples/rnavar/index.html)          | [Markdown](examples/rnavar/markdown/index.md)          | [JSON](examples/rnavar/json/pipeline-api.json)          |
-| sarek           | nf-core/sarek — variant calling & annotation | [HTML](examples/sarek/index.html)           | [Markdown](examples/sarek/markdown/index.md)           | [JSON](examples/sarek/json/pipeline-api.json)           |
-| wf-metagenomics | Oxford Nanopore metagenomics workflow        | [HTML](examples/wf-metagenomics/index.html) | [Markdown](examples/wf-metagenomics/markdown/index.md) | [JSON](examples/wf-metagenomics/json/pipeline-api.json) |
+| Pipeline        | Description                                  | HTML                                        | Markdown                                               | Table                                             | JSON                                                    |
+| --------------- | -------------------------------------------- | ------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------------- |
+| hello           | Nextflow hello-world pipeline                | [HTML](examples/hello/index.html)           | [Markdown](examples/hello/markdown/index.md)           | [Table](examples/hello/table/README.md)           | [JSON](examples/hello/json/pipeline-api.json)           |
+| rnaseq-nf       | Simple RNA-seq pipeline                      | [HTML](examples/rnaseq-nf/index.html)       | [Markdown](examples/rnaseq-nf/markdown/index.md)       | [Table](examples/rnaseq-nf/table/README.md)       | [JSON](examples/rnaseq-nf/json/pipeline-api.json)       |
+| rnavar          | nf-core/rnavar — RNA variant calling         | [HTML](examples/rnavar/index.html)          | [Markdown](examples/rnavar/markdown/index.md)          | [Table](examples/rnavar/table/README.md)          | [JSON](examples/rnavar/json/pipeline-api.json)          |
+| sarek           | nf-core/sarek — variant calling & annotation | [HTML](examples/sarek/index.html)           | [Markdown](examples/sarek/markdown/index.md)           | [Table](examples/sarek/table/README.md)           | [JSON](examples/sarek/json/pipeline-api.json)           |
+| wf-metagenomics | Oxford Nanopore metagenomics workflow        | [HTML](examples/wf-metagenomics/index.html) | [Markdown](examples/wf-metagenomics/markdown/index.md) | [Table](examples/wf-metagenomics/table/README.md) | [JSON](examples/wf-metagenomics/json/pipeline-api.json) |

docs/index.md

@@ -30,6 +30,13 @@ Python or Javadoc for Java.
 
     One file per section — integrates with static site generators like Astro, MkDocs, Zensical and Docusaurus.
 
+
+-   :material-table:{ .lg .middle } __Table__
+
+    ---
+
+    Compact terraform-docs-style Markdown tables with marker injection and selective section rendering.
+
 -   :material-code-json:{ .lg .middle } __JSON__
 
     ---

docs/running.md

@@ -6,14 +6,14 @@
 nf-docs generate PIPELINE_PATH [OPTIONS]
 ```
 
-| Option              | Description                                                 |
-| ------------------- | ----------------------------------------------------------- |
-| `--format`, `-f`    | Output format: `html` (default), `markdown`, `json`, `yaml` |
-| `--output`, `-o`    | Output file or directory (default: `docs/`)                 |
-| `--title`, `-t`     | Custom title                                                |
-| `--no-cache`        | Force fresh extraction                                      |
-| `--verbose`, `-v`   | Debug output                                                |
-| `--language-server` | Path to Language Server JAR                                 |
+| Option              | Description                                                          |
+| ------------------- | -------------------------------------------------------------------- |
+| `--format`, `-f`    | Output format: `html` (default), `markdown`, `table`, `json`, `yaml` |
+| `--output`, `-o`    | Output file or directory (default: `docs/`)                          |
+| `--title`, `-t`     | Custom title                                                         |
+| `--no-cache`        | Force fresh extraction                                               |
+| `--verbose`, `-v`   | Debug output                                                         |
+| `--language-server` | Path to Language Server JAR                                          |
 
 ```bash
 # HTML — single shareable file
@@ -24,6 +24,10 @@ nf-docs generate . -f markdown -o docs/
 
 # JSON — pipe to file or other tools
 nf-docs generate . -f json > api.json
+
+# Table — compact terraform-docs-style tables
+nf-docs generate . -f table -o docs/
+
 ```
 
 ### Other commands
@@ -82,3 +86,43 @@ docs/
 ### JSON / YAML
 
 Structured data for programmatic use, CI/CD pipelines, or custom tooling.
+
+### Table
+
+A single `README.md` with compact Markdown tables — inspired by
+[terraform-docs](https://github.com/terraform-docs/terraform-docs).
+
+Supports **marker-based injection** into existing README files:
+
+```markdown
+# My Pipeline
+
+Some intro text.
+
+<!-- BEGIN_NF_DOCS -->
+<!-- END_NF_DOCS -->
+
+Other content below.
+```
+
+Running `nf-docs generate . -f table -o .` will inject the generated tables between the markers,
+leaving the rest of the file untouched.
+
+#### Selective sections with template tags
+
+Control which sections appear by adding `{{ section }}` placeholders between the markers:
+
+```markdown
+<!-- BEGIN_NF_DOCS -->
+
+{{ inputs }}
+
+{{ config }}
+
+<!-- END_NF_DOCS -->
+```
+
+Available tags: `{{ header }}`, `{{ inputs }}`, `{{ config }}`, `{{ workflows }}`,
+`{{ processes }}`, `{{ functions }}`.
+
+If no tags are present, all sections are rendered (the default).

src/nf_docs/cli.py

@@ -161,9 +161,9 @@ def main() -> None:
     "--format",
     "-f",
     "output_format",
-    type=click.Choice(["json", "yaml", "markdown", "md", "html"], case_sensitive=False),
+    type=click.Choice(["json", "yaml", "markdown", "md", "html", "table"], case_sensitive=False),
     default="html",
-    help="Output format: json, yaml, markdown (or md), html (default: html)",
+    help="Output format: json, yaml, markdown (or md), html, table (default: html)",
 )
 @click.option(
     "--output",
@@ -268,7 +268,7 @@ def generate(
             # Determine output
             if output_path:
                 # Write to file/directory
-                if output_format in ("markdown", "html"):
+                if output_format in ("markdown", "html", "table"):
                     created_files = renderer.render_to_directory(pipeline, output_path)
                     progress.update(task, description="Rendering complete")
                 else:
@@ -294,7 +294,7 @@ def generate(
 
         # Output results after progress display is gone
         if output_path:
-            if output_format in ("markdown", "html"):
+            if output_format in ("markdown", "html", "table"):
                 file_word = "file" if len(created_files) == 1 else "files"
                 console.print(
                     f"[green]Created {len(created_files)} {file_word} in {output_path}[/green]"

src/nf_docs/renderers/__init__.py

@@ -6,16 +6,19 @@
 - YAML: Structured data, human-friendly
 - Markdown: Documentation files
 - HTML: Self-contained static site
+ Table: Compact Markdown tables (terraform-docs style)
 """
 
 from nf_docs.renderers.base import BaseRenderer
 from nf_docs.renderers.html import HTMLRenderer
 from nf_docs.renderers.json import JSONRenderer
 from nf_docs.renderers.markdown import MarkdownRenderer
+from nf_docs.renderers.table import TableRenderer
 from nf_docs.renderers.yaml import YAMLRenderer
 
 __all__ = [
     "BaseRenderer",
+    "TableRenderer",
     "JSONRenderer",
     "YAMLRenderer",
     "MarkdownRenderer",
@@ -43,6 +46,7 @@ def get_renderer(format: str) -> type[BaseRenderer]:
         "markdown": MarkdownRenderer,
         "md": MarkdownRenderer,
         "html": HTMLRenderer,
+        "table": TableRenderer,
     }
 
     format_lower = format.lower()