diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst new file mode 100644 index 000000000..b0685e84a --- /dev/null +++ b/docs/developer-guide.rst @@ -0,0 +1,80 @@ +.. Copyright 2023 Lawrence Livermore National Security, LLC and other + Benchpark Project Developers. See the top-level COPYRIGHT file for details. + + SPDX-License-Identifier: Apache-2.0 + +=============== +Developer Guide +=============== + +This guide is intended for people who want to work on Benchpark itself. + +-------- +Overview +-------- + +Benchpark is designed with several roles in mind: + +#. **Users**, who want to install, run, and analyze performance of HPC benchmarks +#. **Application Developers**, who want to share their benchmarks. +#. **Procurement Teams**, who curate workload representation, evaluate and + monitor system progress at HPC centers. +#. **HPC Vendors**, who understand the curated workload of HPC centers, propose + systems. +#. **Benchpark Developers**, who work on Benchpark, add new features, and try + to make the jobs of benchmark developers and users easier. + +This gets us to the key concepts in Benchpark's software design: + +- Specs: expressions for describing experiments and compute systems +- Packages: Python modules that build benchmarks according to a spec. + +------------------- +Directory Structure +------------------- + +So that you can familiarize yourself with the project, we will start with a +high-level view of Benchpark's directory structure: + +.. code-block:: none + + benchpark/ + bin/ + benchpark <- main benchpark executable + benchpark-python <- execute python scripts using benchpark library + + docs/ <- source for this documentation + + experiments/ <- experiment specs + + lib/ + benchpark/ <- benchpark library + scripts/ <- scripts for common benchpark use cases + + modifiers/ <- modifier definitions + + repo/ <- benchmarks are defined here + **/application.py <- ramble application spec + **/package.py <- spack package spec + + systems/ <- system specs + +---------------------- +Updating Documentation +---------------------- + +To build the documentation, requirements can be easily installed from ``.github/workflows/requirements/docs.txt``, using: + +.. code-block:: bash + + pip install -r .github/workflows/requirements/docs.txt + +This requires ``python>=3.11`` (or try an earlier version of sphinx). After updating the documentation, render the pages with the following: + +.. code-block:: bash + + cd docs + make html + +Then, open ``_build/html/index.html`` in a browser to view the rendered +documentation. diff --git a/docs/index.rst b/docs/index.rst index 0f0d0bc43..06913ed9a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -54,6 +54,12 @@ add-a-dryrun update-a-system-config +.. toctree:: + :maxdepth: 1 + :caption: Developer Docs + + developer-guide + .. toctree:: :maxdepth: 1 :caption: Benchpark Utils