README as .md and wrap cmd_process outputs

docs/source/howto/data.rst

@@ -104,7 +104,7 @@ For our beloved ``MultiplyAddWorkChain``, we obtain the following:
 
     $ tree -a dump-multiply_add
     dump-multiply_add
-    ├── README
+    ├── README.md
     ├── .aiida_node_metadata.yaml
     ├── 01-multiply
     │  ├── .aiida_node_metadata.yaml
@@ -123,12 +123,12 @@ For our beloved ``MultiplyAddWorkChain``, we obtain the following:
             ├── _scheduler-stdout.txt
             └── aiida.out
 
-The ``README`` file provides a description of the directory structure, as well as useful information about the top-level
-process. Further, numbered subdirectories are created for each step of the workflow, resulting in the ``01-multiply``
-and ``02-ArithmeticAddCalculation`` folders. The raw calculation input and output files ``aiida.in`` and ``aiida.out``
-of the ``ArithmeticAddCalculation`` are placed in ``inputs`` and ``outputs``. In addition, these also contain
-the submission script ``_aiidasubmit.sh``, as well as the scheduler stdout and stderr, ``_scheduler-stdout.txt`` and
-``_scheduler-stderr.txt``, respectively. Lastly, the source code of the ``multiply`` ``calcfunction`` presenting the
+The ``README.md`` file provides a description of the directory structure, as well as useful information about the
+top-level process. Further, numbered subdirectories are created for each step of the workflow, resulting in the
+``01-multiply`` and ``02-ArithmeticAddCalculation`` folders. The raw calculation input and output files ``aiida.in`` and
+``aiida.out`` of the ``ArithmeticAddCalculation`` are placed in ``inputs`` and ``outputs``. In addition, these also
+contain the submission script ``_aiidasubmit.sh``, as well as the scheduler stdout and stderr, ``_scheduler-stdout.txt``
+and ``_scheduler-stderr.txt``, respectively. Lastly, the source code of the ``multiply`` ``calcfunction`` presenting the
 first step of the workflow is contained in the ``source_file``.
 
 Upon having a closer look at the directory, we also find the hidden ``.aiida_node_metadata.yaml`` files, which are

src/aiida/tools/dumping/processes.py

@@ -71,7 +71,7 @@ def _generate_default_dump_path(process_node: ProcessNode) -> Path:
 
     @staticmethod
     def _generate_readme(process_node: ProcessNode, output_path: Path) -> None:
-        """Generate README file in main dumping directory.
+        """Generate README.md file in main dumping directory.
 
         :param process_node: `CalculationNode` or `WorkflowNode`.
         :param output_path: Output path for dumping.
@@ -88,15 +88,17 @@ def _generate_readme(process_node: ProcessNode, output_path: Path) -> None:
             get_workchain_report,
         )
 
+        pk = process_node.pk
+
         _readme_string = textwrap.dedent(
             f"""\
         This directory contains the files involved in the calculation/workflow
-        `{process_node.process_label} <{process_node.pk}>` run with AiiDA.
+        `{process_node.process_label} <{pk}>` run with AiiDA.
 
         Child calculations/workflows (also called `CalcJob`s/`CalcFunction`s and `WorkChain`s/`WorkFunction`s in AiiDA
         jargon) run by the parent workflow are contained in the directory tree as sub-folders and are sorted by their
         creation time. The directory tree thus mirrors the logical execution of the workflow, which can also be queried
-        by running `verdi process status {process_node.pk}` on the command line.
+        by running `verdi process status {pk}` on the command line.
 
         By default, input and output files of each calculation can be found in the corresponding "inputs" and "outputs"
         directories (the former also contains the hidden ".aiida" folder with machine-readable job execution settings).
@@ -109,7 +111,7 @@ def _generate_readme(process_node: ProcessNode, output_path: Path) -> None:
 
         # `verdi process status`
         process_status = format_call_graph(calc_node=process_node, max_depth=None, call_link_label=True)
-        _readme_string += f'\n\n\nOutput of `verdi process status {process_node.pk}:`\n\n{process_status}'
+        _readme_string += f'\n\n\nOutput of `verdi process status {pk}`:\n\n```shell\n{process_status}\n```'
 
         # `verdi process report`
         # Copied over from `cmd_process`
@@ -122,13 +124,13 @@ def _generate_readme(process_node: ProcessNode, output_path: Path) -> None:
         else:
             process_report = f'Nothing to show for node type {process_node.__class__}'
 
-        _readme_string += f'\n\n\nOutput of `verdi process report {process_node.pk}`:\n\n{process_report}'
+        _readme_string += f'\n\n\nOutput of `verdi process report {pk}`:\n\n```shell\n{process_report}\n```'
 
         # `verdi process show`?
         process_show = get_node_info(node=process_node)
-        _readme_string += f'\n\n\nOutput of `verdi process show {process_node.pk}`:\n\n{process_show}'
+        _readme_string += f'\n\n\nOutput of `verdi process show {pk}`:\n\n```shell\n{process_show}\n```'
 
-        (output_path / 'README').write_text(_readme_string)
+        (output_path / 'README.md').write_text(_readme_string)
 
     @staticmethod
     def _generate_child_node_label(index: int, link_triple: LinkTriple) -> str:

tests/tools/dumping/test_processes.py

@@ -122,7 +122,7 @@ def test_dump(generate_calculation_node_io, generate_workchain_node_io, tmp_path
     return_path = process_dumper.dump(process_node=wc_node, output_path=dump_parent_path)
 
     assert dump_parent_path.is_dir()
-    assert (dump_parent_path / 'README').is_file()
+    assert (dump_parent_path / 'README.md').is_file()
     assert return_path == dump_parent_path
 
 
@@ -454,9 +454,9 @@ def test_generate_parent_readme(tmp_path, generate_workchain_multiply_add):
 
     process_dumper._generate_readme(process_node=wc_node, output_path=tmp_path)
 
-    assert (tmp_path / 'README').is_file()
+    assert (tmp_path / 'README.md').is_file()
 
-    with open(tmp_path / 'README', 'r') as dumped_file:
+    with open(tmp_path / 'README.md', 'r') as dumped_file:
         contents = dumped_file.read()
 
     assert 'This directory contains' in contents