From 740063470be11bd1cdc623f843ec7daf94432a81 Mon Sep 17 00:00:00 2001 From: Martin Shetty <1972005+martukas@users.noreply.github.com> Date: Sun, 3 Nov 2024 03:42:36 -0800 Subject: [PATCH] documentation improvements --- docs/README.md | 14 ++++++++---- docs/docs.sh | 38 +++++++++++++++++++++----------- docs/purchasing/README.md | 4 +--- docs/scripts/make_parts.py | 4 +--- docs/scripts/make_wiring.py | 44 +++++++++++++------------------------ docs/wiring/README.md | 6 +++-- 6 files changed, 56 insertions(+), 54 deletions(-) diff --git a/docs/README.md b/docs/README.md index a68759356..28c0193b7 100644 --- a/docs/README.md +++ b/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 ``` diff --git a/docs/docs.sh b/docs/docs.sh index 25d9acf80..7528e4767 100755 --- a/docs/docs.sh +++ b/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 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,16 +73,20 @@ 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() { @@ -89,9 +94,8 @@ launch_browser() { } 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 # ######## diff --git a/docs/purchasing/README.md b/docs/purchasing/README.md index 5d434d529..f0f3ee701 100644 --- a/docs/purchasing/README.md +++ b/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). diff --git a/docs/scripts/make_parts.py b/docs/scripts/make_parts.py index 72becce6e..761f9145c 100755 --- a/docs/scripts/make_parts.py +++ b/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() diff --git a/docs/scripts/make_wiring.py b/docs/scripts/make_wiring.py index 77ace9272..c87326ff2 100644 --- a/docs/scripts/make_wiring.py +++ b/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__": diff --git a/docs/wiring/README.md b/docs/wiring/README.md index b8af45f59..555e48533 100644 --- a/docs/wiring/README.md +++ b/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 +```