feat: add configurable output formats for inspection reports

CHANGELOG.md

@@ -1,5 +1,8 @@
 # v0.6.6 (Upcoming)
 
+### New Features
+* Added specifiable output format for reports based on file extension. Reports saved with `.md` extension use Markdown format, `.html`/`.htm` use HTML format with styled output, and all others default to RST format. [#153](https://github.com/NeurodataWithoutBorders/nwbinspector/issues/153)
+
 ### New Checks
 * Added `check_file_extension` for NWB file extension best practice recommendations (`.nwb`, `.nwb.h5`, or `.nwb.zarr`) [#625](https://github.com/NeurodataWithoutBorders/nwbinspector/pull/625)
 * Added `check_units_table_duration` to detect if the duration of spike times in a Units table exceeds a threshold (default: 1 year), which may indicate spike_times are in the wrong units or there is a data quality issue.

docs/user_guide/using_the_command_line_interface.rst

@@ -127,6 +127,25 @@ There are many common options you can specify with flags, such as saving the rep
     nwbinspector path/to/my/data.nwb --report-file-path path/to/my/nwbinspector_report.txt
 
 
+The report format is automatically determined based on the file extension:
+
+- ``.md`` - Markdown format with ``#``/``##``/``###`` section headings
+- ``.html`` or ``.htm`` - HTML format with professional styling, color-coded importance levels, and a styled summary section
+- All other extensions (including ``.txt``, ``.rst``) - RST format with ``=``/``-``/``~`` section headings (default)
+
+For example, to save a Markdown-formatted report:
+
+::
+
+    nwbinspector path/to/my/data.nwb --report-file-path path/to/my/nwbinspector_report.md
+
+Or an HTML report with styled output:
+
+::
+
+    nwbinspector path/to/my/data.nwb --report-file-path path/to/my/nwbinspector_report.html
+
+
 If a report file from a previous run of the inspector is already present at the location, it can be overwritten with
 the ``-o`` or ``--overwrite`` flag...
 

docs/user_guide/using_the_library.rst

@@ -147,6 +147,69 @@ See the section on :ref:`advanced_streaming_api` for more customized usage of th
 
 
 
+Formatting Inspection Results
+-----------------------------
+
+The NWBInspector provides several formatter classes for rendering inspection results in different formats. Each formatter
+inherits from :py:class:`~nwbinspector._formatting.MessageFormatter` and provides format-specific rendering of section
+headers and report summaries.
+
+**Available Formatters:**
+
+- :py:class:`~nwbinspector.RstFormatter` - RST format with ``=``/``-``/``~`` section headings (default)
+- :py:class:`~nwbinspector.MarkdownFormatter` - Markdown format with ``#``/``##``/``###`` section headings
+- :py:class:`~nwbinspector.HtmlFormatter` - HTML format with professional styling and color-coded importance levels
+
+To format inspection results, use the :py:func:`~nwbinspector.format_messages` function with your chosen formatter:
+
+.. code-block:: python
+
+    from nwbinspector import inspect_nwbfile, format_messages, RstFormatter
+
+    messages = list(inspect_nwbfile(nwbfile_path="path_to_single_nwbfile"))
+    formatted_report = format_messages(messages=messages, formatter=RstFormatter())
+    print(formatted_report)
+
+For Markdown output:
+
+.. code-block:: python
+
+    from nwbinspector import inspect_nwbfile, format_messages, MarkdownFormatter
+
+    messages = list(inspect_nwbfile(nwbfile_path="path_to_single_nwbfile"))
+    formatted_report = format_messages(messages=messages, formatter=MarkdownFormatter())
+
+    with open("report.md", "w") as f:
+        f.write(formatted_report)
+
+For HTML output with professional styling:
+
+.. code-block:: python
+
+    from nwbinspector import inspect_nwbfile, format_messages, HtmlFormatter
+
+    messages = list(inspect_nwbfile(nwbfile_path="path_to_single_nwbfile"))
+    formatted_report = format_messages(messages=messages, formatter=HtmlFormatter())
+
+    with open("report.html", "w") as f:
+        f.write(formatted_report)
+
+The ``format_messages`` function also accepts optional parameters for customizing the report organization:
+
+.. code-block:: python
+
+    from nwbinspector import inspect_nwbfile, format_messages, MarkdownFormatter
+
+    messages = list(inspect_nwbfile(nwbfile_path="path_to_single_nwbfile"))
+    formatted_report = format_messages(
+        messages=messages,
+        formatter=MarkdownFormatter(),
+        levels=["importance", "file_path"],  # Custom organization levels
+        reverse=[True, False],  # Reverse order for each level
+    )
+
+
+
 Examining the Default Check Registry
 ------------------------------------
 

src/nwbinspector/__init__.py

@@ -14,7 +14,9 @@
     print_to_console,
     save_report,
     MessageFormatter,
-    FormatterOptions,
+    RstFormatter,
+    MarkdownFormatter,
+    HtmlFormatter,
     InspectorOutputJSONEncoder,
 )
 from ._organization import organize_messages
@@ -52,7 +54,9 @@
     "print_to_console",
     "save_report",
     "MessageFormatter",
-    "FormatterOptions",
+    "RstFormatter",
+    "MarkdownFormatter",
+    "HtmlFormatter",
     "organize_messages",
     "__version__",
     # Public submodules