WIP: sketch out source code architecture for apidoc (#48)

- initial commit: add benchpark version -- Benchpark driver needs to be python
  to import modules. Spack gets around this by having a top-level bash script
  that calls main.py which has the driver code.

Co-authored-by: pearce8 <[email protected]>

bin/benchpark

@@ -8,6 +8,8 @@ import shutil
 import shlex
 import sys
 
+import benchpark
+
 DEBUG = False
 
 def debug_print(message):
@@ -25,6 +27,7 @@ def main():
     actions = {}
     benchpark_list(subparsers, actions)
     benchpark_setup(subparsers, actions)
+    benchpark_version(subparsers, actions)
 
     args = parser.parse_args()
 
@@ -113,6 +116,11 @@ def benchpark_setup(subparsers, actions_dict):
 
     actions_dict["setup"] = benchpark_setup_handler
 
+def benchpark_version(subparsers, actions_dict):
+    list_parser = subparsers.add_parser("version", help="Benchpark version")
+    list_parser.add_argument('sublist', nargs='?')
+    actions_dict["version"] = benchpark_version_handler
+
 def run_command(command_str, env=None):
     subprocess.run(
         shlex.split(command_str),
@@ -243,5 +251,8 @@ Further steps are needed to run the experiments (ramble -P -D . on)
 """
     print(instructions)
 
+def benchpark_version_handler(args):
+    print(benchpark.benchpark_version)
+
 if __name__ == "__main__":
     main()

docs/conf.py

@@ -6,6 +6,19 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+import os
+import sys
+
+from sphinx.ext.apidoc import main as sphinx_apidoc
+
+# -- Benchpark customizations ------------------------------------------------
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.append(os.path.abspath("../lib/benchpark/benchpark"))
+print(sys.path)
+
+
 project = 'Benchpark'
 copyright = '2023, LLNS LLC'
 author = 'Olga Pearce, Alec Scott, Peter Scheibel, Greg Becker, Riyaz Haque, and Nathan Hanford'
@@ -15,6 +28,7 @@
 
 extensions = [
     'sphinx_rtd_theme',
+    "sphinx.ext.autodoc",
 ]
 
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.spack-env']
@@ -26,3 +40,20 @@
 
 html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
+
+# -- Run sphinx-apidoc -------------------------------------------------
+# Remove any previous API docs
+# ReadtheDocs doesn't clean up after previous builds
+# Without this, the API Docs will never actually update
+apidoc_args = [
+    "--force",  # Overwrite existing files
+    "--no-toc",  # Don't create a table of contents file
+    "--output-dir=.",  # Directory to place all output
+    "--module-first",  # emit module docs before submodule docs
+]
+sphinx_apidoc(
+    apidoc_args
+    + [
+        "../lib/benchpark/benchpark",
+    ]
+)

lib/benchpark/benchpark/__init__.py

@@ -0,0 +1,16 @@
+__version__ = "0.1.0"
+benchpark_version = __version__
+
+
+def __try_int(v):
+    try:
+        return int(v)
+    except ValueError:
+        return v
+
+
+benchpark_version_info = tuple([__try_int(v) for v in __version__.split(".")])
+
+
+__all__ = ["benchpark_version_info", "benchpark_version"]
+