diff --git a/bash_completion.sh b/bash_completion.sh index 08d499cb7..d1600bd67 100644 --- a/bash_completion.sh +++ b/bash_completion.sh @@ -557,7 +557,7 @@ _buildtest () ;; tutorial-examples) local cmds="aws spack" - local opts="--help -h" + local opts="--help -h -d --dryrun --failfast -w --write" COMPREPLY=( $( compgen -W "${cmds}" -- "${cur}" ) ) if [[ $cur == -* ]] ; then COMPREPLY=( $( compgen -W "${opts}" -- "${cur}" ) ) diff --git a/buildtest/cli/__init__.py b/buildtest/cli/__init__.py index 71c9867c4..1b7e5da10 100644 --- a/buildtest/cli/__init__.py +++ b/buildtest/cli/__init__.py @@ -595,17 +595,32 @@ def stylecheck_menu(self): def tutorial_menu(self): parser = self.subparsers.choices["tutorial-examples"] - unittests_args = [ + tutorial = [ ( ["examples"], { "help": "Select which tutorial examples to build", "choices": ["aws", "spack"], }, - ) + ), + ( + ["-d", "--dryrun"], + { + "action": "store_true", + "help": "Just print commands that will be generated without running them", + }, + ), + ( + ["-w", "--write"], + { + "action": "store_true", + "help": "Write the content of each command to file", + }, + ), + (["--failfast"], {"action": "store_true", "help": "Stop on first failure"}), ] - for args, kwargs in unittests_args: + for args, kwargs in tutorial: parser.add_argument(*args, **kwargs) def unittest_menu(self): diff --git a/buildtest/main.py b/buildtest/main.py index f5da9db69..07a4bac15 100644 --- a/buildtest/main.py +++ b/buildtest/main.py @@ -55,10 +55,7 @@ from buildtest.system import BuildTestSystem from buildtest.tools.editor import set_editor from buildtest.tools.stylecheck import run_style_checks -from buildtest.tools.tutorialexamples import ( - generate_aws_examples, - generate_tutorial_examples, -) +from buildtest.tools.tutorialexamples import generate_tutorial_examples from buildtest.tools.unittests import run_unit_tests from buildtest.utils.file import ( create_dir, @@ -384,10 +381,12 @@ def main(): ) elif args.subcommands == "tutorial-examples": - if args.examples == "spack": - generate_tutorial_examples() - elif args.examples == "aws": - generate_aws_examples() + generate_tutorial_examples( + examples=args.examples, + dryrun=args.dryrun, + write=args.write, + failfast=args.failfast, + ) elif args.subcommands in ["stylecheck", "style"]: run_style_checks( diff --git a/buildtest/tools/docs.py b/buildtest/tools/docs.py deleted file mode 100644 index 04db46b95..000000000 --- a/buildtest/tools/docs.py +++ /dev/null @@ -1,139 +0,0 @@ -import os -import subprocess - -from buildtest.defaults import BUILDTEST_ROOT, console -from buildtest.exceptions import BuildTestError -from buildtest.utils.file import create_dir, write_file - - -def run(query): - """This method will execute command for the tutorials examples. If returncode - is non-zero we raise exception otherwise we return output of command. - - Args: - query (str): Run a arbitrary shell command. - """ - - print(f"Executing Command: {query}") - command = subprocess.run( - [query], shell=True, check=True, universal_newlines=True, capture_output=True - ) - - # for non-negative returncode - if command.returncode != 0: - raise BuildTestError(f"[red]Returncode: {command.returncode}") - - console.print(f"[green]Returncode: {command.returncode}") - return command.stdout - - -def write_example(fname, command): - """Given a shell command, we will write output to file. We will print first - 10 lines from upon writing file to ensure file was written properly. - - Args: - fname (str): Path to file where output of command will be written - command (str): Command that was executed - - """ - out = f"$ {command} \n" - out += run(command) - write_file(fname, out) - - console.print(f"Writing output to {fname}") - console.rule(fname) - - # read first 10 lines of files written in example - N = 10 - with open(fname, "r") as fd: - firstNlines = fd.readlines()[0:N] - firstNlines = "".join(firstNlines) - - console.print(firstNlines) - - -def build_aws_examples(autogen_dir): - """This method will build AWS examples for the tutorial - - Args: - autogen_dir (str): Directory where auto generated documentation examples will be written. - """ - - build_dir = os.path.join(autogen_dir) - - create_dir(build_dir) - - AWS_EXAMPLE_DIR = os.path.join(BUILDTEST_ROOT, "aws_tutorial") - - commands_to_run = { - f"{build_dir}/hello_build.txt": f"buildtest build -b {AWS_EXAMPLE_DIR}/hello_world/hello.yml", - f"{build_dir}/hello_inspect.txt": "buildtest inspect query -o -t hello_world_example", - f"{build_dir}/multi_compiler_hello_build.txt": f"buildtest build -b {AWS_EXAMPLE_DIR}/hello_world/multi_compiler_hello.yml", - f"{build_dir}/multi_compiler_hello_inspect.txt": "buildtest inspect query -o -t hello_world_multi_compiler/", - f"{build_dir}/compiler_list_yaml.txt": "buildtest config compilers list --yaml", - f"{build_dir}/mpiproc_build.txt": f"buildtest build -b {AWS_EXAMPLE_DIR}/mpiproc.yml", - f"{build_dir}/mpiproc_inspect.txt": "buildtest inspect query -o mpiprocname", - f"{build_dir}/osu_bandwidth_test_build.txt": f"buildtest build -b {AWS_EXAMPLE_DIR}/osu_bandwidth_test.yml", - f"{build_dir}/osu_bandwidth_test_inspect.txt": "buildtest inspect query -o osu_bandwidth osu_bandwidth_perf", - f"{build_dir}/openmp_example_build.txt": f"buildtest build -b {AWS_EXAMPLE_DIR}/openmp_example_custom_compiler.yml", - f"{build_dir}/openmp_example_inspect.txt": "buildtest inspect query -o -t hello_world_openmp_custom_compiler/", - f"{build_dir}/docker_helloworld_build.txt": f"buildtest build -b {BUILDTEST_ROOT}/tutorials/containers/hello_world.yml", - f"{build_dir}/docker_helloworld_inspect.txt": "buildtest inspect query -o -t hello_world_docker", - f"{build_dir}/singularity_helloworld_build.txt": f"buildtest build -b {BUILDTEST_ROOT}/tutorials/containers/hello_world_singularity.yml", - f"{build_dir}/singularity_helloworld_inspect.txt": "buildtest inspect query -o -t hello_world_singularity", - f"{build_dir}/container_executor_list.txt": "buildtest -c $BUILDTEST_ROOT/buildtest/settings/container_executor.yml config executors list --yaml", - f"{build_dir}/container_executor_build.txt": "buildtest -c $BUILDTEST_ROOT/buildtest/settings/container_executor.yml build -b $BUILDTEST_ROOT/tutorials/containers/container_executor/ubuntu.yml", - f"{build_dir}/container_executor_inspect.txt": "buildtest inspect query -o -t -b ubuntu_container_example", - } - - for fname, command in commands_to_run.items(): - write_example(fname, command) - - -def build_spack_examples(autogen_dir): - """This method will build spack examples for the tutorial - - Args: - autogen_dir (str): Directory where auto generated documentation examples will be written. - """ - - build_dir = os.path.join(autogen_dir, "spack", "build") - inspect_dir = os.path.join(autogen_dir, "spack", "inspect") - - create_dir(build_dir) - create_dir(inspect_dir) - - SPACK_EXAMPLE_DIR = os.path.join(BUILDTEST_ROOT, "examples", "spack") - commands_to_run = { - f"{build_dir}/install_specs.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/install_specs.yml", - f"{build_dir}/env_install.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/env_install.yml", - f"{build_dir}/env_create_directory.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/env_create_directory.yml", - f"{build_dir}/env_create_manifest.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/env_create_manifest.yml", - f"{build_dir}/remove_environment_example.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/remove_environment_example.yml", - f"{build_dir}/spack_env_deactivate.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/spack_env_deactivate.yml", - f"{build_dir}/pre_post_cmds.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/pre_post_cmds.yml", - f"{build_dir}/mirror_example.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/mirror_example.yml", - f"{build_dir}/spack_load.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/spack_load.yml", - f"{build_dir}/spack_test.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/spack_test.yml", - f"{build_dir}/spack_test_specs.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/spack_test_specs.yml", - f"{build_dir}/spack_sbatch.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/spack_sbatch.yml", - f"{build_dir}/e4s_testsuite_mpich.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/e4s_testsuite_mpich.yml", - f"{build_dir}/clone_spack.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/clone_spack.yml", - f"{inspect_dir}/install_specs.txt": "buildtest inspect query -o -t install_specs_example", - f"{inspect_dir}/env_install.txt": "buildtest inspect query -t install_in_spack_env", - f"{inspect_dir}/env_create_directory.txt": "buildtest inspect query -o -t spack_env_directory", - f"{inspect_dir}/env_create_manifest.txt": "buildtest inspect query -o -t spack_env_create_from_manifest", - f"{inspect_dir}/spack_env_deactivate.txt": "buildtest inspect query -t spack_env_deactivate_first", - f"{inspect_dir}/remove_environment_example.txt": "buildtest inspect query -t remove_environment_automatically remove_environment_explicit", - f"{inspect_dir}/pre_post_cmds.txt": "buildtest inspect query -o -t run_pre_post_commands", - f"{inspect_dir}/mirror_example.txt": "buildtest inspect query -o -t add_mirror add_mirror_in_spack_env", - f"{inspect_dir}/spack_load.txt": "buildtest inspect query -t spack_load_example", - f"{inspect_dir}/spack_test.txt": "buildtest inspect query -o -t spack_test_m4", - f"{inspect_dir}/spack_test_specs.txt": "buildtest inspect query -o -t spack_test_results_specs_format", - f"{inspect_dir}/spack_sbatch.txt": "buildtest inspect query -t spack_sbatch_example", - f"{inspect_dir}/clone_spack.txt": "buildtest inspect query -o -t clone_spack_automatically clone_spack_and_specify_root", - f"{inspect_dir}/e4s_testsuite_mpich.txt": "buildtest inspect query -o -e -t mpich_e4s_testsuite", - } - - for fname, command in commands_to_run.items(): - write_example(fname, command) diff --git a/buildtest/tools/tutorialexamples.py b/buildtest/tools/tutorialexamples.py index 51f375be6..a1cfd7138 100644 --- a/buildtest/tools/tutorialexamples.py +++ b/buildtest/tools/tutorialexamples.py @@ -1,57 +1,239 @@ import getpass import os import shutil +import subprocess import sys from buildtest.cli.clean import clean from buildtest.config import SiteConfiguration -from buildtest.defaults import BUILDTEST_ROOT, TUTORIALS_SETTINGS_FILE -from buildtest.tools.docs import build_aws_examples, build_spack_examples -from buildtest.utils.file import create_dir, is_dir, is_file +from buildtest.defaults import BUILDTEST_ROOT, TUTORIALS_SETTINGS_FILE, console +from buildtest.utils.file import create_dir, is_dir, is_file, write_file -def generate_tutorial_examples(): +def generate_tutorial_examples(examples, dryrun=None, write=None, failfast=None): """This method is the entry point for "buildtest tutorial-examples" command which generates documentation examples for Buildtest Tutorial. + + Args: + examples (str): The type of examples to generate. This can be either 'spack' or 'aws' + dryrun (bool, optional): If set to True, we will perform a dryrun. Default is None. + write (bool, optional): If set to True, we will write output to file. Default is None. + failfast (bool, optional): If set to True, we will exit on first failure. Default is None. """ - if getpass.getuser() != "spack" or os.getenv("HOME") != "/home/spack": - sys.exit( - "This script can only be run inside container: ghcr.io/buildtesters/buildtest_spack:latest" + settings_file = None + autogen_examples_dir = None + moduletool = "none" + + if examples == "spack": + + if getpass.getuser() != "spack" or os.getenv("HOME") != "/home/spack": + sys.exit( + "This script can only be run inside container: ghcr.io/buildtesters/buildtest_spack:latest" + ) + + autogen_examples_dir = os.path.join( + BUILDTEST_ROOT, "docs", "buildtest_tutorial_examples" ) + settings_file = TUTORIALS_SETTINGS_FILE + moduletool = "none" - autogen_examples_dir = os.path.join( - BUILDTEST_ROOT, "docs", "buildtest_tutorial_examples" - ) + else: + + if getpass.getuser() != "ubuntu" or os.getenv("HOME") != "/home/ubuntu": + sys.exit( + "This script can only be run in AWS instance using E4SPro image. Please check the AWS Market Place: https://aws.amazon.com/marketplace for the image " + ) - config = SiteConfiguration(settings_file=TUTORIALS_SETTINGS_FILE) + autogen_examples_dir = os.path.join(BUILDTEST_ROOT, "docs", "aws_examples") + settings_file = os.path.join(BUILDTEST_ROOT, "buildtest", "settings", "aws.yml") + + moduletool = "environment-modules" + + config = SiteConfiguration(settings_file=settings_file) config.detect_system() - config.validate() + config.validate(moduletool=moduletool) - if is_file(autogen_examples_dir): - os.remove(autogen_examples_dir) + if write: - if is_dir(autogen_examples_dir): - shutil.rmtree(autogen_examples_dir) + if is_file(autogen_examples_dir): + os.remove(autogen_examples_dir) - create_dir(autogen_examples_dir) + if is_dir(autogen_examples_dir): + shutil.rmtree(autogen_examples_dir) - clean(config, yes=True) - build_spack_examples(autogen_examples_dir) + create_dir(autogen_examples_dir) + clean(config, yes=True) -def generate_aws_examples(): - if getpass.getuser() != "ubuntu" or os.getenv("HOME") != "/home/ubuntu": - sys.exit( - "This script can only be run in AWS instance using E4SPro image. Please check the AWS Market Place: https://aws.amazon.com/marketplace for the image " + if examples == "spack": + build_spack_examples( + autogen_examples_dir, dryrun=dryrun, write=write, failfast=failfast + ) + else: + build_aws_examples( + autogen_examples_dir, dryrun=dryrun, write=write, failfast=failfast ) - autogen_examples_dir = os.path.join(BUILDTEST_ROOT, "docs", "aws_examples") - config = SiteConfiguration( - settings_file=os.path.join(BUILDTEST_ROOT, "buildtest", "settings", "aws.yml") +def run(query): + """This method will execute command for the tutorials examples. If returncode + is non-zero we raise exception otherwise we return output of command. + + Args: + query (str): Run a arbitrary shell command. + """ + + console.print(f"Executing Command: {query}") + command = subprocess.run( + [query], shell=True, check=True, universal_newlines=True, capture_output=True ) - config.detect_system() - config.validate(moduletool="environment-modules") - build_aws_examples(autogen_examples_dir) + return (command.stdout, command.returncode) + + +def write_example(fname, command, content): + """Given a shell command, we will write output to file. We will print first + 10 lines from upon writing file to ensure file was written properly. + + Args: + fname (str): Path to file where output of command will be written + command (str): Command that was executed + content (str): Content to write to file + + """ + out = f"$ {command} \n" + out += content + write_file(fname, out) + + console.print(f"Writing output to {fname}") + console.rule(fname) + + # read first 10 lines of files written in example + N = 10 + with open(fname, "r") as fd: + firstNlines = fd.readlines()[0:N] + firstNlines = "".join(firstNlines) + + console.print(firstNlines) + + +def build_aws_examples(build_dir, dryrun=None, write=None, failfast=None): + """This method will build AWS examples for the tutorial + + Args: + build_dir (str): Directory where auto generated documentation examples will be written. + dryrun (bool, optional): If True we print commands to run and return. If False we execute commands. Defaults to None. + write (bool, optional): If True we write output to file. Defaults to None. + failfast (bool, optional): If True we exit on first failure. Defaults to None. + """ + + AWS_EXAMPLE_DIR = os.path.join(BUILDTEST_ROOT, "aws_tutorial") + + commands_to_run = { + f"{build_dir}/hello_build.txt": f"buildtest build -b {AWS_EXAMPLE_DIR}/hello_world/hello.yml", + f"{build_dir}/hello_inspect.txt": "buildtest inspect query -o -t hello_world_example", + f"{build_dir}/multi_compiler_hello_build.txt": f"buildtest build -b {AWS_EXAMPLE_DIR}/hello_world/multi_compiler_hello.yml", + f"{build_dir}/multi_compiler_hello_inspect.txt": "buildtest inspect query -o -t hello_world_multi_compiler/", + f"{build_dir}/compiler_list_yaml.txt": "buildtest config compilers list --yaml", + f"{build_dir}/mpiproc_build.txt": f"buildtest build -b {AWS_EXAMPLE_DIR}/mpiproc.yml", + f"{build_dir}/mpiproc_inspect.txt": "buildtest inspect query -o mpiprocname", + f"{build_dir}/osu_bandwidth_test_build.txt": f"buildtest build -b {AWS_EXAMPLE_DIR}/osu_bandwidth_test.yml", + f"{build_dir}/osu_bandwidth_test_inspect.txt": "buildtest inspect query -o osu_bandwidth osu_bandwidth_perf", + f"{build_dir}/openmp_example_build.txt": f"buildtest build -b {AWS_EXAMPLE_DIR}/openmp_example_custom_compiler.yml", + f"{build_dir}/openmp_example_inspect.txt": "buildtest inspect query -o -t hello_world_openmp_custom_compiler/", + f"{build_dir}/docker_helloworld_build.txt": f"buildtest build -b {BUILDTEST_ROOT}/tutorials/containers/hello_world.yml", + f"{build_dir}/docker_helloworld_inspect.txt": "buildtest inspect query -o -t hello_world_docker", + f"{build_dir}/singularity_helloworld_build.txt": f"buildtest build -b {BUILDTEST_ROOT}/tutorials/containers/hello_world_singularity.yml", + f"{build_dir}/singularity_helloworld_inspect.txt": "buildtest inspect query -o -t hello_world_singularity", + f"{build_dir}/container_executor_list.txt": "buildtest -c $BUILDTEST_ROOT/buildtest/settings/container_executor.yml config executors list --yaml", + f"{build_dir}/container_executor_build.txt": "buildtest -c $BUILDTEST_ROOT/buildtest/settings/container_executor.yml build -b $BUILDTEST_ROOT/tutorials/containers/container_executor/ubuntu.yml", + f"{build_dir}/container_executor_inspect.txt": "buildtest inspect query -o -t -b ubuntu_container_example", + } + + if dryrun: + for command in commands_to_run.values(): + console.print(command) + return + + for fname, command in commands_to_run.items(): + content, retcode = run(command) + + # for non-negative returncode + if retcode != 0: + console.print(f"[red]Returncode: {retcode}") + if failfast: + sys.exit(1) + + console.print(f"[green]Returncode: {retcode}") + + if write: + write_example(fname=fname, command=command, content=content) + + +def build_spack_examples(autogen_dir, dryrun=None, write=None, failfast=None): + """This method will build spack examples for the tutorial + + Args: + autogen_dir (str): Directory where auto generated documentation examples will be written. + dryrun (bool, optional): If True we print commands to run and return. If False we execute commands. Defaults to None. + write (bool, optional): If True we write output to file. Defaults to None. + failfast (bool, optional): If True we exit on first failure. Defaults to None. + """ + + build_dir = os.path.join(autogen_dir, "spack", "build") + inspect_dir = os.path.join(autogen_dir, "spack", "inspect") + + create_dir(build_dir) + create_dir(inspect_dir) + + SPACK_EXAMPLE_DIR = os.path.join(BUILDTEST_ROOT, "examples", "spack") + commands_to_run = { + f"{build_dir}/install_specs.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/install_specs.yml", + f"{build_dir}/env_install.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/env_install.yml", + f"{build_dir}/env_create_directory.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/env_create_directory.yml", + f"{build_dir}/env_create_manifest.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/env_create_manifest.yml", + f"{build_dir}/remove_environment_example.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/remove_environment_example.yml", + f"{build_dir}/spack_env_deactivate.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/spack_env_deactivate.yml", + f"{build_dir}/pre_post_cmds.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/pre_post_cmds.yml", + f"{build_dir}/mirror_example.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/mirror_example.yml", + f"{build_dir}/spack_load.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/spack_load.yml", + f"{build_dir}/spack_test.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/spack_test.yml", + f"{build_dir}/spack_test_specs.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/spack_test_specs.yml", + f"{build_dir}/spack_sbatch.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/spack_sbatch.yml", + f"{build_dir}/e4s_testsuite_mpich.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/e4s_testsuite_mpich.yml", + f"{build_dir}/clone_spack.txt": f"buildtest build -b {SPACK_EXAMPLE_DIR}/clone_spack.yml", + f"{inspect_dir}/install_specs.txt": "buildtest inspect query -o -t install_specs_example", + f"{inspect_dir}/env_install.txt": "buildtest inspect query -t install_in_spack_env", + f"{inspect_dir}/env_create_directory.txt": "buildtest inspect query -o -t spack_env_directory", + f"{inspect_dir}/env_create_manifest.txt": "buildtest inspect query -o -t spack_env_create_from_manifest", + f"{inspect_dir}/spack_env_deactivate.txt": "buildtest inspect query -t spack_env_deactivate_first", + f"{inspect_dir}/remove_environment_example.txt": "buildtest inspect query -t remove_environment_automatically remove_environment_explicit", + f"{inspect_dir}/pre_post_cmds.txt": "buildtest inspect query -o -t run_pre_post_commands", + f"{inspect_dir}/mirror_example.txt": "buildtest inspect query -o -t add_mirror add_mirror_in_spack_env", + f"{inspect_dir}/spack_load.txt": "buildtest inspect query -t spack_load_example", + f"{inspect_dir}/spack_test.txt": "buildtest inspect query -o -t spack_test_m4", + f"{inspect_dir}/spack_test_specs.txt": "buildtest inspect query -o -t spack_test_results_specs_format", + f"{inspect_dir}/spack_sbatch.txt": "buildtest inspect query -t spack_sbatch_example", + f"{inspect_dir}/clone_spack.txt": "buildtest inspect query -o -t clone_spack_automatically clone_spack_and_specify_root", + f"{inspect_dir}/e4s_testsuite_mpich.txt": "buildtest inspect query -o -e -t mpich_e4s_testsuite", + } + + if dryrun: + for command in commands_to_run.values(): + console.print(command) + return + + for fname, command in commands_to_run.items(): + content, retcode = run(command) + + # for non-negative returncode + if retcode != 0: + console.print(f"[red]Returncode: {retcode}") + if failfast: + sys.exit(1) + + console.print(f"[green]Returncode: {retcode}") + + if write: + write_example(fname=fname, command=command, content=content) diff --git a/docs/buildspecs/aws.rst b/docs/buildspecs/aws.rst index 80764da49..5d28bf3ab 100644 --- a/docs/buildspecs/aws.rst +++ b/docs/buildspecs/aws.rst @@ -1,3 +1,5 @@ +.. _buildtest_aws: + Buildtest Tutorial on AWS ========================= diff --git a/docs/contributing/build_documentation.rst b/docs/contributing/build_documentation.rst index ecc6d38c2..4d13ef0e9 100644 --- a/docs/contributing/build_documentation.rst +++ b/docs/contributing/build_documentation.rst @@ -91,16 +91,21 @@ on google style see: https://google.github.io/styleguide/pyguide.html Generating Documentation Examples for Buildtest Tutorial ---------------------------------------------------------- -The documentation examples for the buildtest tutorial are run inside the container image -ghcr.io/buildtesters/buildtest_spack:latest which means that some of the example output needs to be generated manually. There -is a script `doc-examples.py `_ that -is responsible for auto-generating the documentation examples inside the container. +The ``buildtest tutorial-examples`` command is used for auto-generating examples for the buildtest tutorial. This command will serve the purpose of semi-automating +the test creation where examples can't be run on readthedocs platform. Shown below is the command usage for ``buildtest tutorial-examples``. + +.. command-output:: buildtest tutorial-examples --help + :shell: + +The documentation examples for the :ref:`buildtest_spack_integration` are run inside the container image +`ghcr.io/buildtesters/buildtest_spack:latest `_ which means that some of the +example output needs to be generated manually. To get into the container along with the buildtest codebase you will need to run the following commands .. Note:: - You may need to `source /etc/profile` in your container if you see module command is not found. + You may need to `source /etc/profile` in your container if you see **module command is not found**. .. Note:: @@ -118,13 +123,22 @@ Once you are in the container run the following commands cd /home/spack/buildtest source scripts/spack_container/setup.sh -Once your setup is complete, you can auto-generate documentation examples by running the following:: +Once your setup is complete, you can run the spack generated examples in dryrun mode by running:: + + buildtest tutorial-examples spack --dryrun + +This will print a list of buildtest commands that will be run without actually executing them. If you want to test the examples, you can +run the following command:: + + buildtest tutorial-examples spack - buildtest tutorial-examples +If you want buildtest to write the changes to the documentation, you will need to use the ``--write`` flag which will run the example tests and write +the output to file. -Alternatively, the script can also be invoked via python as shown below:: +If you want to generate the examples for :ref:`buildtest_aws`, you will need to access the E4S Pro container image and clone buildtest, checkout to your +branch and then run the command:: - python scripts/spack_container/doc-examples.py + buildtest tutorial-examples aws Please verify all the auto-generated examples that will be used in the documentation. Once you are content with all the changes please add all the changes via ``git add``. diff --git a/tests/tools/test_tutorialexamples.py b/tests/tools/test_tutorialexamples.py deleted file mode 100644 index 6d5a6a3af..000000000 --- a/tests/tools/test_tutorialexamples.py +++ /dev/null @@ -1,8 +0,0 @@ -import pytest - -from buildtest.tools.tutorialexamples import generate_tutorial_examples - - -def test_buildtest_tutorial_examples(): - with pytest.raises(SystemExit): - generate_tutorial_examples()