diff --git a/README.md b/README.md index cdba7f2..f1ee176 100644 --- a/README.md +++ b/README.md @@ -7,26 +7,64 @@ Converts EPICS vdct templates to pure msi compatible EPICS db templates -This is where you should write a short paragraph that describes what your module does, -how it does it, and why people should use it. +This tool is designed to modify an EPICS support module in order to remove +its dependency on the vdct tool. This is useful for support modules that we +want to build with the upstream vanilla EPICS base that does not include vdct. Source | :---: | :---: PyPI | `pip install vdct2template` Releases | -This is where you should put some images or code snippets that illustrate -some relevant examples. If it is a library then you might put some -introductory code here: -```python -from vdct2template import __version__ +## Installation -print(f"Hello vdct2template {__version__}") -``` +To install the latest release from PyPI, create a virtual environment and +pip install like this: -Or if it is a commandline tool then you might put some example commands here: +```bash +python -m venv venv +source venv/bin/activate +pip install vdct2template ``` -python -m vdct2template --version -``` + +## Usage + +
$ vdct2template --help
+                                                                                          
+ Usage: vdct2template [OPTIONS] FOLDER                                                    
+                                                                                          
+                          VDCT to template conversion function.
+
+  • This function assumes that all referenced VDCT files in the expand() blocks will be   
+    in the same folder.                                                                   
+  • We can use the builder.py file to check for direct references to template files Use   
+    --no-use-builder to disable this feature. Direct references to a template file is an  
+    error because we need to modify all macro names to add a _ prefix in templated files. 
+  • Files referenced in expand() blocks will have their macro names updated to all have a 
+    _ prefix, because MSI does not support substituting a macro with it's own name and    
+    passing a default. This is a workaround to that limitation.                           
+  • The original expands() block is replaced with a series of substitute MSI directives   
+    and an include MSI directive.                                                         
+  • The resulting set of templates can be expanded natively by MSI without the need for   
+    VDCT.                                                                                 
+  • The DB files created by such an expansion should be equivalent to the original VDCT   
+    generated ones.                                                                       
+
+╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮
+│ *    folder      DIRECTORY  folder of vdb files to convert to template files.          │
+│                             [default: None]                                            │
+│                             [required]                                                 │
+╰────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
+│ --version                                         Print the version and exit           │
+│ --use-builder           --no-use-builder          Use the builder.py file to look for  │
+│                                                   direct references to template files. │
+│                                                   [default: use-builder]               │
+│ --builder                                   FILE  Path to the builder file.            │
+│                                                   [default: None]                      │
+│ --help                                            Show this message and exit.          │
+╰────────────────────────────────────────────────────────────────────────────────────────╯
+
+
\ No newline at end of file diff --git a/src/vdct2template/__main__.py b/src/vdct2template/__main__.py index 92b605b..6e1314b 100644 --- a/src/vdct2template/__main__.py +++ b/src/vdct2template/__main__.py @@ -9,7 +9,7 @@ __all__ = ["main"] -cli = typer.Typer() +cli = typer.Typer(rich_markup_mode="markdown") def version_callback(value: bool): @@ -47,29 +47,28 @@ def main( ), ): """ - VDCT to template conversion function. + ### VDCT to template conversion function. - Converts all VDCT files in the folder to template files. - - This function assumes that all referenced VDCT files in the expand() blocks + - This function assumes that all referenced VDCT files in the expand() blocks will be in the same folder. - We can use the builder.py file to check for direct references to template files + - We can use the builder.py file to check for direct references to template files Use --no-use-builder to disable this feature. Direct references to a template file is an error because we need to modify all macro names to add a _ prefix in templated files. - This tool converts VDCT files to template files. It looks for expand() blocks - in the VDCT files. If these are found then it will also convert all of the - referenced files to template files. In referenced files the macro names will - all have _ prefix added because MSI does not support substituting a macro with + - Files referenced in expand() blocks will have their macro names updated to + all have a _ prefix, because MSI does not support substituting a macro with it's own name and passing a default. This is a workaround to that limitation. - The original expands() block is replaced with a series of substitute - and include MSI directives. + - The original expands() block is replaced with a series of substitute + MSI directives and an include MSI directive. + + - The resulting set of templates can be expanded natively by MSI without the + need for VDCT. - The resulting set of templates can be expanded natively by MSI without the - need for VDCT. The resulting DB files should be equivalent to the original. + - The DB files created by such an expansion should be equivalent to the + original VDCT generated ones. """ if use_builder: