add dynamic omniperf version number in installation guide

Signed-off-by: Peter Jun Park <[email protected]> add datatemplate
ROCm · Jun 25, 2024 · 18effce · 18effce
1 parent bc34059
commit 18effce
Show file tree

Hide file tree

Showing 4 changed files with 63 additions and 53 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -28,32 +28,22 @@
 
 import re
 
-from rocm_docs import ROCmDocs
-
 with open("../VERSION", encoding="utf-8") as f:
     match = re.search(r"([0-9.]+)[^0-9.]+", f.read())
     if not match:
         raise ValueError("VERSION not found!")
     version_number = match[1]
 
+extensions = ["rocm_docs", "sphinxcontrib.datatemplates"]
+external_toc_path = "./sphinx/_toc.yml"
+
+left_nav_title = f"Omniperf {version_number} documentation"
+html_theme = "rocm_docs_theme"
+html_theme_options = {"flavor": "rocm"}
+html_title = left_nav_title
+
 project = "omniperf"
 author = "Advanced Micro Devices, Inc."
 copyright = "Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved."
 version = version_number
 release = version_number
-html_title = f"Omniperf {version} documentation"
-
-external_toc_path = "./sphinx/_toc.yml"
-extensions = []
-
-docs_core = ROCmDocs(html_title)
-docs_core.setup()
-
-for sphinx_var in ROCmDocs.SPHINX_VARS:
-    globals()[sphinx_var] = getattr(docs_core, sphinx_var)
-
-# A string of rST that will be included at the beginning of every source file
-# that is read. Adds substitutions that should be available in every file.
-rst_prolog = """
-.. |TM| replace:: ™
-"""
diff --git a/docs/install/core-install.rst b/docs/install/core-install.rst
@@ -9,15 +9,15 @@ Installing and deploying Omniperf
 
 Omniperf consists of two installation components.
 
-* :ref:`Omniperf core installation <core-install>`
+* :ref:`Omniperf core installation <core-install>` (client-side)
 
   * Provides the core application profiling capability.
   * Allows the collection of performance counters, filtering by hardware
     block, dispatch, kernel, and more.
   * Provides a CLI-based analysis mode.
   * Provides a standalone web interface for importing analysis metrics.
 
-* :doc:`Grafana server for Omniperf <grafana-setup>` (optional)
+* :doc:`Grafana server for Omniperf <grafana-setup>` (server-side) (*optional*)
 
   * Hosts the MongoDB backend and Grafana instance.
   * Is packaged in a Docker container for easy setup.
@@ -96,31 +96,35 @@ Installation steps
    from `<https://github.com/ROCm/omniperf/releases>`__. From there, untar and
    navigate into the top-level directory.
 
-   .. code-block:: shell
+   .. datatemplate:nodata::
+
+      .. code-block:: shell
 
-      tar xfz omniperf-v{__VERSION__}.tar.gz
-      cd omniperf-v{__VERSION__}
+         tar xfz omniperf-v{{ config.version }}.tar.gz
+         cd omniperf-v{{ config.version }}
 
 #. Next, install Python dependencies and complete the Omniperf configuration and
    install process.
 
-   .. code-block:: shell
+   .. datatemplate:nodata::
 
-      # define top-level install path
-      export INSTALL_DIR=<your-top-level-desired-install-path>
+      .. code-block:: shell
 
-      # install python deps
-      python3 -m pip install -t ${INSTALL_DIR}/python-libs -r requirements.txt
+         # define top-level install path
+         export INSTALL_DIR=<your-top-level-desired-install-path>
 
-      # configure Omniperf for shared install
-      mkdir build
-      cd build
-      cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_DIR}/{__VERSION__} \
-              -DPYTHON_DEPS=${INSTALL_DIR}/python-libs \
-              -DMOD_INSTALL_PATH=${INSTALL_DIR}/modulefiles ..
+         # install python deps
+         python3 -m pip install -t ${INSTALL_DIR}/python-libs -r requirements.txt
 
-      # install
-      make install
+         # configure Omniperf for shared install
+         mkdir build
+         cd build
+         cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_DIR}/{{ config.version }} \
+                 -DPYTHON_DEPS=${INSTALL_DIR}/python-libs \
+                 -DMOD_INSTALL_PATH=${INSTALL_DIR}/modulefiles ..
+
+         # install
+         make install
 
    .. tip::
 
@@ -130,10 +134,12 @@ Installation steps
 #. Upon successful installation, your top-level installation directory should
    look like this.
 
-   .. code-block:: shell
+   .. datatemplate:nodata::
 
-      $ ls $INSTALL_DIR
-      modulefiles  {__VERSION__}  python-libs
+      .. code-block:: shell
+
+         $ ls $INSTALL_DIR
+         modulefiles  {{ config.version }}  python-libs
 
 .. _core-install-modulefiles:
 
@@ -145,17 +151,19 @@ use with `Lmod <https://lmod.readthedocs.io>`_. On systems that support Lmod,
 you can register the Omniperf modulefile directory and setup your environment
 for execution of Omniperf as follows.
 
-.. code-block:: shell
+.. datatemplate:nodata::
+
+   .. code-block:: shell
 
-   $ module use $INSTALL_DIR/modulefiles
-   $ module load omniperf
-   $ which omniperf
-   /opt/apps/omniperf/{__VERSION__}/bin/omniperf
+      $ module use $INSTALL_DIR/modulefiles
+      $ module load omniperf
+      $ which omniperf
+      /opt/apps/omniperf/{{ config.version }}/bin/omniperf
 
-   $ omniperf --version
-   ROC Profiler:   /opt/rocm-5.1.0/bin/rocprof
+      $ omniperf --version
+      ROC Profiler:   /opt/rocm-5.1.0/bin/rocprof
 
-   omniperf (v{__VERSION__})
+      omniperf (v{{ config.version }})
 
 .. tip::
 
@@ -171,10 +179,12 @@ settings to enable access to the command line binary. If you installed Python
 dependencies in a shared location, also update your ``PYTHONPATH``
 configuration.
 
-.. code-block:: shell
+.. datatemplate:nodata::
+
+   .. code-block:: shell
 
-   export PATH=$INSTALL_DIR/{__VERSION__}/bin:$PATH
-   export PYTHONPATH=$INSTALL_DIR/python-libs
+      export PATH=$INSTALL_DIR/{{ config.version }}/bin:$PATH
+      export PYTHONPATH=$INSTALL_DIR/python-libs
 
 .. _core-install-rocprof-var:
 

diff --git a/docs/sphinx/requirements.in b/docs/sphinx/requirements.in
@@ -1 +1,2 @@
 rocm-docs-core==1.4.0
+sphinxcontrib.datatemplates==0.11.0
diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt
@@ -28,6 +28,8 @@ click==8.1.7
     # via sphinx-external-toc
 cryptography==42.0.8
     # via pyjwt
+defusedxml==0.7.1
+    # via sphinxcontrib-datatemplates
 deprecated==1.2.14
     # via pygithub
 docutils==0.21.2
@@ -36,7 +38,7 @@ docutils==0.21.2
     #   myst-parser
     #   pydata-sphinx-theme
     #   sphinx
-fastjsonschema==2.19.1
+fastjsonschema==2.20.0
     # via rocm-docs-core
 gitdb==4.0.11
     # via gitpython
@@ -88,6 +90,7 @@ pyyaml==6.0.1
     #   myst-parser
     #   rocm-docs-core
     #   sphinx-external-toc
+    #   sphinxcontrib-datatemplates
 requests==2.32.3
     # via
     #   pygithub
@@ -111,7 +114,9 @@ sphinx==7.3.7
     #   sphinx-design
     #   sphinx-external-toc
     #   sphinx-notfound-page
-sphinx-book-theme==1.1.2
+    #   sphinxcontrib-datatemplates
+    #   sphinxcontrib-runcmd
+sphinx-book-theme==1.1.3
     # via rocm-docs-core
 sphinx-copybutton==0.5.2
     # via rocm-docs-core
@@ -123,6 +128,8 @@ sphinx-notfound-page==1.0.2
     # via rocm-docs-core
 sphinxcontrib-applehelp==1.0.8
     # via sphinx
+sphinxcontrib-datatemplates==0.11.0
+    # via -r docs/sphinx/requirements.in
 sphinxcontrib-devhelp==1.0.6
     # via sphinx
 sphinxcontrib-htmlhelp==2.0.5
@@ -131,6 +138,8 @@ sphinxcontrib-jsmath==1.0.1
     # via sphinx
 sphinxcontrib-qthelp==1.0.7
     # via sphinx
+sphinxcontrib-runcmd==0.2.0
+    # via sphinxcontrib-datatemplates
 sphinxcontrib-serializinghtml==1.1.10
     # via sphinx
 tomli==2.0.1
@@ -139,7 +148,7 @@ typing-extensions==4.12.2
     # via
     #   pydata-sphinx-theme
     #   pygithub
-urllib3==2.2.1
+urllib3==2.2.2
     # via
     #   pygithub
     #   requests