documentation improvements

docs/README.md

@@ -1,16 +1,16 @@
 # Documentation
 
-The documentation created here is written in reStructuredTexT and generated using [Sphinx](https://www.sphinx-doc.org/en/master/) via a Github action.
+The documentation created here is written in reStructuredTexT and generated using [Sphinx](https://www.sphinx-doc.org/en/master/) via a GitHub action.
 
 ## reStructuredText
 
-reStructured text is similar to Markdown in that it is ASCII formatted text that is mostly human readable and contains directives that specify how the text should be rendered in HTML, and other output formats.
+reStructured text is similar to Markdown in that it is ASCII formatted text that is mostly human-readable and contains directives that specify how the text should be rendered in HTML, and other output formats.
 
 reStructuredText is more complex than Markdown and allows for much greater flexibility in formatting as well as additional features such as *directives* that act like variables/macros that are defined once and expanded in place.
 
 ## Document Generation
 
-The Github action rules can be found in `.github/workflows/docs.yml`
+The GitHub action rules can be found in `.github/workflows/docs.yml`
 
 C++ API documentation is generated using [Doxygen](https://github.com/doxygen/doxygen)
 
@@ -34,7 +34,13 @@ To generate the documentation, run:
 ./docs.sh build
 ```
 
-If the directories are polluted and you want a clean slate:
+To render wiring harnesses only:
+
+```shell
+./docs.sh wire ./path/to/dir/or/file.yml
+```
+
+If the directories are polluted, and you want a clean slate:
 ```shell
 ./docs.sh clean
 ```

docs/docs.sh

@@ -28,12 +28,13 @@ print_help() {
 Utility script for generating Ventilator documentation.
 
 The following options are available:
-  install     One-time installation of build toolchain and dependencies
-  clean       Clean build directories
-  build       Generate documentation
-  view        Open generated documentation in browser
-  check       Check for broken links
-  help/-h     Display this help info
+  install      One-time installation of build toolchain and dependencies
+  clean        Clean build directories
+  build        Generate documentation
+  wire <path>  Render wiring harness diagrams for specified path, which may be a file or a directory
+  view         Open generated documentation in browser
+  check        Check for broken links
+  help/-h      Display this help info
 EOF
 }
 
@@ -72,26 +73,29 @@ install_linux() {
   sudo apt --yes install docker-ce
 
   docker pull lycheeverse/lychee
-  echo "If you wish to use \`./docs.sh check\` to check validity of links locally, please follow installation instructions at https://github.com/lycheeverse/lychee"
+}
+
+process_wiring() {
+  source "${HOME}/.profile"
+  poetry install --no-root --quiet
+  poetry run wiring "$1"
 }
 
 build_all() {
   source "${HOME}/.profile"
-  poetry install
-  poetry run wiring -d ./wiring
-  poetry run parts -f ./purchasing/parts.json
+  poetry install --no-root --quiet
+  poetry run wiring ./wiring
+  poetry run parts ./purchasing/parts.json
   poetry run make html
-  touch ./_build/html/.nojekyll
 }
 
 launch_browser() {
   python3 -m webbrowser "${OUTPUT_DIR}/html/index.html"
 }
 
 check_links() {
-  echo "If you wish to use \`./docs.sh check\` to check validity of links locally, please follow installation instructions at https://github.com/lycheeverse/lychee"
+  touch ./_build/html/.nojekyll
   docker run --init --rm -w /input -v "$(pwd)/..":/input lycheeverse/lychee -c ./docs/lychee.toml --no-ignore .
-#  lychee ..
 }
 
 ########
@@ -125,6 +129,14 @@ elif [ "$1" == "build" ]; then
   build_all
   exit_good
 
+#########
+# BUILD #
+#########
+elif [ "$1" == "wire" ]; then
+  ensure_not_root
+  process_wiring "$2"
+  exit_good
+
 ########
 # VIEW #
 ########

docs/purchasing/README.md

@@ -38,6 +38,4 @@ The syntax/semantics for a part definition are as follows:
 
 ## Scripts
 
-[make_parts.py](make_parts.py) - reads [parts.json](parts.json) and from it generates `parts.rst`,with tables and link nodes which can then be rendered by sphinx
-
-[make_parts.sh](make_parts.sh) - wrapper script that ensures correct operating system and runs the python script from within this directory
+The `parts.rst` file, with tables and link nodes will be generated as when you run [docs/docs.sh build](../docs.sh).

docs/scripts/make_parts.py

@@ -118,11 +118,9 @@ def main():
     parser = argparse.ArgumentParser()
 
     parser.add_argument(
-        "-f",
-        "--file",
+        "file",
         type=json_arg,
         help="File to process",
-        required=True,
     )
 
     args = parser.parse_args()

docs/scripts/make_wiring.py

@@ -25,19 +25,10 @@
 import pandas
 
 
-def yaml_arg(path: str) -> Path:
+def path_arg(path: str) -> Path:
     ret = Path(path)
-    if ret.suffix not in (".yml", ".yaml"):
-        raise argparse.ArgumentTypeError(f"Not a YAML file: {ret}")
-    if not ret.is_file():
-        raise argparse.ArgumentTypeError(f"File not found: {ret}")
-    return ret
-
-
-def dir_arg(path: str) -> Path:
-    ret = Path(path)
-    if not ret.is_dir():
-        raise argparse.ArgumentTypeError(f"Not a directory: {ret}")
+    if not ret.exists():
+        raise argparse.ArgumentTypeError(f"Path does not exist: {ret}")
     return ret
 
 
@@ -62,34 +53,29 @@ def generate_wiring_diagram(yaml_file: Path) -> None:
     print(f"Generating wiring diagram for {yaml_file}")
     wireviz.parse(yaml_file, output_formats=("gv", "html", "png", "svg", "tsv"))
     tsv_file = yaml_file.parent / (yaml_file.stem + ".bom.tsv")
-    print(f"Will modify {tsv_file}")
+    print(f"Injecting purchasing xrefs into {tsv_file}")
     decorate_table(tsv_file)
 
 
 def main():
     parser = argparse.ArgumentParser()
-    group = parser.add_mutually_exclusive_group(required=True)
 
-    group.add_argument(
-        "-f",
-        "--file",
-        type=yaml_arg,
-        help="File to process",
-    )
-    group.add_argument(
-        "-d",
-        "--directory",
-        type=dir_arg,
-        help="Directory to process",
+    parser.add_argument(
+        "path",
+        type=path_arg,
+        help="File or directory to process",
     )
 
     args = parser.parse_args()
 
-    if args.file:
-        generate_wiring_diagram(args.file)
-    elif args.directory:
-        for file in args.directory.rglob("**/*.yml"):
+    if args.path.is_dir():
+        print(f"Processing all files in {args.path}")
+        for file in args.path.rglob("**/*.yml"):
             generate_wiring_diagram(file)
+    elif args.path.is_file():
+        if args.path.suffix not in (".yml", ".yaml"):
+            raise argparse.ArgumentTypeError(f"Not a YAML file: {args.path}")
+        generate_wiring_diagram(args.path)
 
 
 if __name__ == "__main__":

docs/wiring/README.md

@@ -27,6 +27,8 @@ Where
 
 ## Scripts
 
-[decorate_table.py](decorate_table.py) - takes a `*.bom.tsv` file and modifies it so that each entry in the `P/N` column is wrapped in RST link-to-reference syntax. Thus, when a the table is embedded in an RST file, the part numbers are rendered as links to the purchasing/parts page
+To render the wiring documentation, use [docs/docs.sh](../docs.sh) script as follows:
 
-[make_wiring.sh](make_wiring.sh) - runs wireviz to generate BOM and diagram, then runs `decorate_table.py` to add links to BOM
+```shell
+./docs.sh wire ./path/to/dir/or/file.yml
+```