From 129984a126a5e409bb2f7b88d219a98c8da443bf Mon Sep 17 00:00:00 2001 From: Shahzeb Siddiqui Date: Fri, 28 Oct 2022 15:06:24 -0400 Subject: [PATCH 1/4] add section on auto-generating examples for buildtest tutorial --- docs/contributing/build_documentation.rst | 28 ++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/contributing/build_documentation.rst b/docs/contributing/build_documentation.rst index e762ce68d..6d79935ce 100644 --- a/docs/contributing/build_documentation.rst +++ b/docs/contributing/build_documentation.rst @@ -80,4 +80,30 @@ DocStrings We have enabled `napolean extension `_ to support Google style docstring. Please follow this format when you are writting docstring for buildtest codebase. For more details -on google style see: https://google.github.io/styleguide/pyguide.html \ No newline at end of file +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 auto-generated manually. There +is a script `doc-examples.py `_ that +is responsible for auto-generating the documentation examples inside the container. To get started you will need to run the +following commands. + +.. code-block:: console + + docker run -it -v $BUILDTEST_ROOT:/home/spack/buildtest ghcr.io/buildtesters/buildtest_spack:latest + cd /home/spack/buildtest + source scripts/spack_container/setup.py + + +You will need to volume mount $BUILDTEST_ROOT into `/home/spack/buildtest` in-order to get your buidltest code-base accessible inside container. + +Once you setup the environment, please run the python script and it will auto-generate the examples as follows:: + + python scripts/spack_container/doc-examples.py + +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 +``git add``. + From 57365401315f9da3207e11f0d6033114431fc376 Mon Sep 17 00:00:00 2001 From: Shahzeb Siddiqui Date: Fri, 28 Oct 2022 15:12:49 -0400 Subject: [PATCH 2/4] rephrase a few sentences --- docs/contributing/build_documentation.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/contributing/build_documentation.rst b/docs/contributing/build_documentation.rst index 6d79935ce..3611d63d3 100644 --- a/docs/contributing/build_documentation.rst +++ b/docs/contributing/build_documentation.rst @@ -86,7 +86,7 @@ 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 auto-generated manually. There +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. To get started you will need to run the following commands. @@ -98,12 +98,13 @@ following commands. source scripts/spack_container/setup.py -You will need to volume mount $BUILDTEST_ROOT into `/home/spack/buildtest` in-order to get your buidltest code-base accessible inside container. +You will need to volume mount **$BUILDTEST_ROOT** into `/home/spack/buildtest` in-order to get buildtest code-base accessible inside +the container. -Once you setup the environment, please run the python script and it will auto-generate the examples as follows:: +Once you setup is complete, please run the python script and it will auto-generate the documentation examples :: python scripts/spack_container/doc-examples.py -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 -``git add``. +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``. From a3ab9ae3f906e29bbbabba1280efda2694aa797e Mon Sep 17 00:00:00 2001 From: Shahzeb Siddiqui Date: Mon, 31 Oct 2022 10:33:44 -0400 Subject: [PATCH 3/4] type in documentation its setup.sh not setup.py --- docs/contributing/build_documentation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/build_documentation.rst b/docs/contributing/build_documentation.rst index 3611d63d3..0fe95e1cc 100644 --- a/docs/contributing/build_documentation.rst +++ b/docs/contributing/build_documentation.rst @@ -95,13 +95,13 @@ following commands. docker run -it -v $BUILDTEST_ROOT:/home/spack/buildtest ghcr.io/buildtesters/buildtest_spack:latest cd /home/spack/buildtest - source scripts/spack_container/setup.py + source scripts/spack_container/setup.sh You will need to volume mount **$BUILDTEST_ROOT** into `/home/spack/buildtest` in-order to get buildtest code-base accessible inside the container. -Once you setup is complete, please run the python script and it will auto-generate the documentation examples :: +Once you setup is complete, please run the python script and it will auto-generate the documentation examples:: python scripts/spack_container/doc-examples.py From 3bc4ae27b1ae6160298916ebe67d5674b50accfe Mon Sep 17 00:00:00 2001 From: Shahzeb Siddiqui Date: Thu, 3 Nov 2022 11:52:02 -0400 Subject: [PATCH 4/4] add note on source /etc/profile --- docs/contributing/build_documentation.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/contributing/build_documentation.rst b/docs/contributing/build_documentation.rst index 0fe95e1cc..8c5db9e77 100644 --- a/docs/contributing/build_documentation.rst +++ b/docs/contributing/build_documentation.rst @@ -91,13 +91,16 @@ is a script `doc-examples.py