DEPICT : Document EPICs daTabase

Description

Script to extract records, their name, type and an eventual description put in comment above and format them into a csv file or markdown file. If no comments is found above the PV the field DESC is used .

Any record field can be added to the output file thanks to the --field argument.

An option exists to apply the Depict script to all .db and .template files located a given folder.

Input file

#HEADER of my file

#Description of my record
record(ao, "$(PREFIX):myName") {
        field(SIZV,"1024")
        field(LEN,"1024")
        field(EGU ,"mV")
}

#Description of my 2nd record
record(ao, "$(PREFIX):myName2") {
        field(SIZV,"1024")
        field(LEN,"1024")
        field(EGU,A)
}

record(ao, "$(PREFIX):myName2") {
        field(DESC, "desc of 3rd pv")
        field(SIZV,"1024")
        field(LEN,"1024")
        field(EGU,A)
}

Output file in CSV

Name;Type;EGU;Description
$(PREFIX):myName;ao;mV;Description of my record
$(PREFIX):myName2;ao;A;Description of my 2nd record
$(PREFIX):myName3;ao;A;desc of 3rd pv

Or in Markdown

| Name               | Type | EGU | Description                   |
|--------------------|------|-----|-------------------------------|
| \$(PREFIX):myName  | ao   | mV  | Description of my record      |
| \$(PREFIX):myName2 | ao   | A   | Description of my 2nd record  |
| \$(PREFIX):myName3 | ao   | A   | desc of 3rd pv                |

equivalent to

Name	Type	EGU	Description
$(PREFIX):myName	ao	mV	Description of my record
$(PREFIX):myName2	ao	A	Description of my 2nd record
$(PREFIX):myName3	ao	A	desc of 3rd pv

Build using Poetry

First, install Poetry. Refer to the Poetry for instructions.

To build the project, you can run:

poetry install
poetry build

##Execution

poetry run depict -f md misc/example.template /tmp/yeah.md

poetry run depict -f md -r misc/example_folder /tmp/depict_example

poetry run depict -f md -r \
    misc/example_folder /tmp/depict_example \
    --field EGU --field DRVL --field DRVH

poetry run depict -f md -r --one-file \
    misc/example_folder /tmp/depict_example/output.md \
    --field EGU --field DRVL --field DRVH

Usage

Usage: depict [OPTIONS] INPUT [OUTPUT]

  DEPICT: Document EPICs daTabase.

  Serialize EPICS records from INPUT to a csv or markdown table file OUTPUT.
  INPUT must be an EPICS database file.

  If --recursive is specified, INPUT must be a directory instead. If
  --recursive is specified, but not --one-file, OUTPUT must be a directory and
  must be specified.

  If OUTPUT isn't specified, output the content to the terminal.

Options:
  -v, --verbose          Increase verbosity, can be specified up to 5 times
  -f, --format [csv|md]  Output format. For md, '$' in the output file are
                         escaped by prefixing them with '\'
  -r, --recursive        Recursively use depict on all .template files found
                         in the input folder.

                         New files are created in the output folder and have
                         the same name as the .template files but with .md or
                         .csv extension, depending on the chosen format.
  --one-file             With --recursive, output is a single file. When this
                         option is specified, OUTPUT must be a file.
  --field TEXT           Record field to include. Can be specified several
                         times.
  --version              Show the version and exit.
  --help                 Show this message and exit.