diff --git a/README.md b/README.md index b1480e8..e49949f 100644 --- a/README.md +++ b/README.md @@ -44,15 +44,19 @@ $ python setup.py install Usage: adr-viewer [OPTIONS] Options: - --adr-path TEXT Directory containing ADR files. [default: doc/adr/] - --output TEXT File to write output to. [default: index.html] - --title TEXT The project title [default: the basename of the current directory] - --serve Serve content at http://localhost:8000/ - --port INT Custom server port [default: 8000] - --help Show this message and exit. + --adr-path TEXT Directory containing ADR files; pass explicitly, read + .adr-dir if it exists or uses doc/adr/ + --output TEXT File to write output to. [default: index.html] + --title TEXT The project title [default: the basename of the current directory] + --serve Serve content at http://localhost:8000/ + --port INTEGER Change port for the server [default: 8000] + --template-dir TEXT Template directory. + --help Show this message and exit. ``` The default for `--adr-path` is `doc/adr/` because this is the default path generated by `adr-tools`. +If `.adr-dir` exists in the directory in which `adr-viewer` was executed, it will be read and used for the `--adr-path`, +following the `adr-tools` convention for overrides. ## Supported Record Types diff --git a/adr_viewer/__init__.py b/adr_viewer/__init__.py index b4363e9..80eb4a2 100644 --- a/adr_viewer/__init__.py +++ b/adr_viewer/__init__.py @@ -1,4 +1,5 @@ -from typing import List +import os +from typing import List, Optional from click import option, command @@ -7,9 +8,37 @@ from adr_viewer.server import run_server +CONVENTIONAL_ADR_DIR = "doc/adr/" +DEFAULT_ADR_DIR_FILE = ".adr-dir" + + +def resolve_adr_dir( + maybe_dir: Optional[str] = None, adr_dir_file: str = DEFAULT_ADR_DIR_FILE +): + """ + If passed something, blindly use it. Otherwise, resolve based on + conventions in the ADR tooling ecosystem. + """ + + def lookup(): + adr_dir = CONVENTIONAL_ADR_DIR + if os.path.exists(adr_dir_file): + with open(adr_dir_file, "r") as file: + adr_dir = file.read().strip() + return adr_dir + + return maybe_dir if maybe_dir else lookup() + + # fmt: off @command() -@option('--adr-path', default='doc/adr/', help='Directory containing ADR files.', show_default=True) +@option('--adr-path', + default=None, + help=f""" + Directory containing ADR files; pass explicitly, + read {DEFAULT_ADR_DIR_FILE} if it exists or uses {CONVENTIONAL_ADR_DIR} + """, + show_default=True) @option('--output', default='index.html', help='File to write output to.', show_default=True) @option('--title', default=None, help='Set the project title', show_default=True) @option('--serve', default=False, help='Serve content at http://localhost:8000/', is_flag=True) @@ -17,6 +46,7 @@ @option('--template-dir', default=None, help='Template directory.', show_default=True) # fmt: on def main(adr_path, output, title, serve, port, template_dir) -> None: + adr_path = resolve_adr_dir(adr_path) adrs: List[Adr] = parse_adr_files("%s/*.md" % adr_path) content = generate_content(adrs, template_dir, title) diff --git a/adr_viewer/test_resolve_adr_path.py b/adr_viewer/test_resolve_adr_path.py new file mode 100644 index 0000000..9cfe06b --- /dev/null +++ b/adr_viewer/test_resolve_adr_path.py @@ -0,0 +1,22 @@ +import tempfile + +from adr_viewer import resolve_adr_dir + + +def test_resolve_adr_path_default(): + assert resolve_adr_dir() == "doc/adr/" + + +def test_resolve_adr_path_explicit(): + assert resolve_adr_dir("docs/adrs") == "docs/adrs" + + +def test_resolve_adr_path_adrdir(): + test_adr_dir_content = "just a test " + with tempfile.NamedTemporaryFile("w") as tmpfile: + tmpfile.write(test_adr_dir_content) + tmpfile.flush() + assert ( + resolve_adr_dir(None, adr_dir_file=tmpfile.name) + == test_adr_dir_content.strip() + )