Merge pull request #241 from YosysHQ/krys/argparse_docs

Add sphinx-argparse to generate usage

docs/source/conf.py

@@ -1,4 +1,10 @@
 #!/usr/bin/env python3
+import os
+import sys
+
+sys.path += [os.path.join(os.path.dirname(__file__),
+ "..", "..", "sbysrc")]
+
 project = 'YosysHQ SBY'
 author = 'YosysHQ GmbH'
 copyright = '2023 YosysHQ GmbH'
@@ -39,3 +45,4 @@
 }
 
 extensions = ['sphinx.ext.autosectionlabel']
+extensions += ['sphinxarg.ext']

docs/source/index.rst

@@ -16,6 +16,7 @@ formal tasks:
 
  install.rst
  quickstart.rst
+ usage.rst
  reference.rst
  autotune.rst
  verilog.rst

docs/source/requirements.txt

@@ -1 +1,2 @@
 furo
+sphinx-argparse

docs/source/usage.rst

@@ -0,0 +1,11 @@
+Using `sby`
+===========
+
+Once SBY is installed and available on the command line as `sby`, either built from source or using
+one of the available CAD suites, it can be called as follows. Note that this information is also
+available via `sby --help`. For more information on installation, see :ref:`install-doc`.
+
+.. argparse::
+ :module: sby_cmdline
+ :func: parser_func
+ :prog: sby

sbysrc/sby.py

@@ -17,88 +17,16 @@
 # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 #
 
-import argparse, json, os, sys, shutil, tempfile, re
+import json, os, sys, shutil, tempfile, re
 ##yosys-sys-path##
+from sby_cmdline import parser_func
 from sby_core import SbyConfig, SbyTask, SbyAbort, SbyTaskloop, process_filename, dress_message
 from sby_jobserver import SbyJobClient, process_jobserver_environment
 import time, platform, click
 
 process_jobserver_environment() # needs to be called early
 
-class DictAction(argparse.Action):
- def __call__(self, parser, namespace, values, option_string=None):
- assert isinstance(getattr(namespace, self.dest), dict), f"Use ArgumentParser.set_defaults() to initialize {self.dest} to dict()"
- name = option_string.lstrip(parser.prefix_chars).replace("-", "_")
- getattr(namespace, self.dest)[name] = values
-
-parser = argparse.ArgumentParser(prog="sby",
- usage="%(prog)s [options] [<jobname>.sby [tasknames] | <dirname>]")
-parser.set_defaults(exe_paths=dict())
-
-parser.add_argument("-d", metavar="<dirname>", dest="workdir",
- help="set workdir name. default: <jobname> or <jobname>_<taskname>. When there is more than one task, use --prefix instead")
-parser.add_argument("--prefix", metavar="<dirname>", dest="workdir_prefix",
- help="set the workdir name prefix. `_<taskname>` will be appended to the path for each task")
-parser.add_argument("-f", action="store_true", dest="force",
- help="remove workdir if it already exists")
-parser.add_argument("-b", action="store_true", dest="backup",
- help="backup workdir if it already exists")
-parser.add_argument("-t", action="store_true", dest="tmpdir",
- help="run in a temporary workdir (remove when finished)")
-parser.add_argument("-T", metavar="<taskname>", action="append", dest="tasknames", default=list(),
- help="add taskname (useful when sby file is read from stdin)")
-parser.add_argument("-E", action="store_true", dest="throw_err",
- help="throw an exception (incl stack trace) for most errors")
-parser.add_argument("-j", metavar="<N>", type=int, dest="jobcount",
- help="maximum number of processes to run in parallel")
-parser.add_argument("--sequential", action="store_true", dest="sequential",
- help="run tasks in sequence, not in parallel")
-
-parser.add_argument("--autotune", action="store_true", dest="autotune",
- help="automatically find a well performing engine and engine configuration for each task")
-parser.add_argument("--autotune-config", dest="autotune_config",
- help="read an autotune configuration file (overrides the sby file's autotune options)")
-
-parser.add_argument("--yosys", metavar="<path_to_executable>",
- action=DictAction, dest="exe_paths")
-parser.add_argument("--abc", metavar="<path_to_executable>",
- action=DictAction, dest="exe_paths")
-parser.add_argument("--smtbmc", metavar="<path_to_executable>",
- action=DictAction, dest="exe_paths")
-parser.add_argument("--witness", metavar="<path_to_executable>",
- action=DictAction, dest="exe_paths")
-parser.add_argument("--suprove", metavar="<path_to_executable>",
- action=DictAction, dest="exe_paths")
-parser.add_argument("--aigbmc", metavar="<path_to_executable>",
- action=DictAction, dest="exe_paths")
-parser.add_argument("--avy", metavar="<path_to_executable>",
- action=DictAction, dest="exe_paths")
-parser.add_argument("--btormc", metavar="<path_to_executable>",
- action=DictAction, dest="exe_paths")
-parser.add_argument("--pono", metavar="<path_to_executable>",
- action=DictAction, dest="exe_paths",
- help="configure which executable to use for the respective tool")
-parser.add_argument("--dumpcfg", action="store_true", dest="dump_cfg",
- help="print the pre-processed configuration file")
-parser.add_argument("--dumptags", action="store_true", dest="dump_tags",
- help="print the list of task tags")
-parser.add_argument("--dumptasks", action="store_true", dest="dump_tasks",
- help="print the list of tasks")
-parser.add_argument("--dumpdefaults", action="store_true", dest="dump_defaults",
- help="print the list of default tasks")
-parser.add_argument("--dumptaskinfo", action="store_true", dest="dump_taskinfo",
- help="output a summary of tasks as JSON")
-parser.add_argument("--dumpfiles", action="store_true", dest="dump_files",
- help="print the list of source files")
-parser.add_argument("--setup", action="store_true", dest="setupmode",
- help="set up the working directory and exit")
-
-parser.add_argument("--init-config-file", dest="init_config_file",
- help="create a default .sby config file")
-parser.add_argument("sbyfile", metavar="<jobname>.sby | <dirname>", nargs="?",
- help=".sby file OR directory containing config.sby file")
-parser.add_argument("arg_tasknames", metavar="tasknames", nargs="*",
- help="tasks to run (only valid when <jobname>.sby is used)")
+parser = parser_func()
 
 args = parser.parse_args()
 

sbysrc/sby_cmdline.py

@@ -0,0 +1,79 @@
+import argparse
+
+class DictAction(argparse.Action):
+ def __call__(self, parser, namespace, values, option_string=None):
+ assert isinstance(getattr(namespace, self.dest), dict), f"Use ArgumentParser.set_defaults() to initialize {self.dest} to dict()"
+ name = option_string.lstrip(parser.prefix_chars).replace("-", "_")
+ getattr(namespace, self.dest)[name] = values
+
+def parser_func():
+ parser = argparse.ArgumentParser(prog="sby",
+ usage="%(prog)s [options] [<jobname>.sby [tasknames] | <dirname>]")
+ parser.set_defaults(exe_paths=dict())
+
+ parser.add_argument("-d", metavar="<dirname>", dest="workdir",
+ help="set workdir name. default: <jobname> or <jobname>_<taskname>. When there is more than one task, use --prefix instead")
+ parser.add_argument("--prefix", metavar="<dirname>", dest="workdir_prefix",
+ help="set the workdir name prefix. `_<taskname>` will be appended to the path for each task")
+ parser.add_argument("-f", action="store_true", dest="force",
+ help="remove workdir if it already exists")
+ parser.add_argument("-b", action="store_true", dest="backup",
+ help="backup workdir if it already exists")
+ parser.add_argument("-t", action="store_true", dest="tmpdir",
+ help="run in a temporary workdir (remove when finished)")
+ parser.add_argument("-T", metavar="<taskname>", action="append", dest="tasknames", default=list(),
+ help="add taskname (useful when sby file is read from stdin)")
+ parser.add_argument("-E", action="store_true", dest="throw_err",
+ help="throw an exception (incl stack trace) for most errors")
+ parser.add_argument("-j", metavar="<N>", type=int, dest="jobcount",
+ help="maximum number of processes to run in parallel")
+ parser.add_argument("--sequential", action="store_true", dest="sequential",
+ help="run tasks in sequence, not in parallel")
+
+ parser.add_argument("--autotune", action="store_true", dest="autotune",
+ help="automatically find a well performing engine and engine configuration for each task")
+ parser.add_argument("--autotune-config", dest="autotune_config",
+ help="read an autotune configuration file (overrides the sby file's autotune options)")
+
+ parser.add_argument("--yosys", metavar="<path_to_executable>",
+ action=DictAction, dest="exe_paths")
+ parser.add_argument("--abc", metavar="<path_to_executable>",
+ action=DictAction, dest="exe_paths")
+ parser.add_argument("--smtbmc", metavar="<path_to_executable>",
+ action=DictAction, dest="exe_paths")
+ parser.add_argument("--witness", metavar="<path_to_executable>",
+ action=DictAction, dest="exe_paths")
+ parser.add_argument("--suprove", metavar="<path_to_executable>",
+ action=DictAction, dest="exe_paths")
+ parser.add_argument("--aigbmc", metavar="<path_to_executable>",
+ action=DictAction, dest="exe_paths")
+ parser.add_argument("--avy", metavar="<path_to_executable>",
+ action=DictAction, dest="exe_paths")
+ parser.add_argument("--btormc", metavar="<path_to_executable>",
+ action=DictAction, dest="exe_paths")
+ parser.add_argument("--pono", metavar="<path_to_executable>",
+ action=DictAction, dest="exe_paths",
+ help="configure which executable to use for the respective tool")
+ parser.add_argument("--dumpcfg", action="store_true", dest="dump_cfg",
+ help="print the pre-processed configuration file")
+ parser.add_argument("--dumptags", action="store_true", dest="dump_tags",
+ help="print the list of task tags")
+ parser.add_argument("--dumptasks", action="store_true", dest="dump_tasks",
+ help="print the list of tasks")
+ parser.add_argument("--dumpdefaults", action="store_true", dest="dump_defaults",
+ help="print the list of default tasks")
+ parser.add_argument("--dumptaskinfo", action="store_true", dest="dump_taskinfo",
+ help="output a summary of tasks as JSON")
+ parser.add_argument("--dumpfiles", action="store_true", dest="dump_files",
+ help="print the list of source files")
+ parser.add_argument("--setup", action="store_true", dest="setupmode",
+ help="set up the working directory and exit")
+
+ parser.add_argument("--init-config-file", dest="init_config_file",
+ help="create a default .sby config file")
+ parser.add_argument("sbyfile", metavar="<jobname>.sby | <dirname>", nargs="?",
+ help=".sby file OR directory containing config.sby file")
+ parser.add_argument("arg_tasknames", metavar="tasknames", nargs="*",
+ help="tasks to run (only valid when <jobname>.sby is used)")
+
+ return parser