From 2d9269d89d3475836b6752c5cfd8dcf06bc89794 Mon Sep 17 00:00:00 2001 From: Julian Geiger Date: Thu, 23 May 2024 21:38:52 +0200 Subject: [PATCH] README as `.md` and wrap `cmd_process` outputs --- docs/source/howto/data.rst | 14 +++++++------- src/aiida/tools/dumping/processes.py | 16 +++++++++------- tests/tools/dumping/test_processes.py | 6 +++--- 3 files changed, 19 insertions(+), 17 deletions(-) diff --git a/docs/source/howto/data.rst b/docs/source/howto/data.rst index 8905a3ea2c..33c9c33aba 100644 --- a/docs/source/howto/data.rst +++ b/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 diff --git a/src/aiida/tools/dumping/processes.py b/src/aiida/tools/dumping/processes.py index 7f8d9fcf15..3d970c421c 100644 --- a/src/aiida/tools/dumping/processes.py +++ b/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: diff --git a/tests/tools/dumping/test_processes.py b/tests/tools/dumping/test_processes.py index cb77f2a5cb..371dcb80a9 100644 --- a/tests/tools/dumping/test_processes.py +++ b/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