Skip to content

document how to generate examples for buildtest tutorial #1289

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shahzebsiddiqui merged 4 commits into from
Nov 3, 2022
Merged

document how to generate examples for buildtest tutorial #1289

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
129984a
add section on auto-generating examples for buildtest tutorial
shahzebsiddiqui Oct 28, 2022
5736540
rephrase a few sentences
shahzebsiddiqui Oct 28, 2022
a3ab9ae
type in documentation its setup.sh not setup.py
shahzebsiddiqui Oct 31, 2022
3bc4ae2
add note on source /etc/profile
shahzebsiddiqui Nov 3, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 31 additions & 1 deletion docs/contributing/build_documentation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,4 +80,34 @@ DocStrings

We have enabled `napolean extension <https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html>`_ 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
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 <https://github.com/buildtesters/buildtest/blob/devel/scripts/spack_container/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.

.. Note::

You may need to `source /etc/profile` in your container if you see module command is not found.

.. 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.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::

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 via ``git add``.