Unverified Commit 704edb08 authored by Maxime Lefrançois's avatar Maxime Lefrançois
Browse files

md: experimental `saref-dev md`, the TS as md-specs-dev Markdown 

Writes target/md/TS-<number>.md (YAML front matter, ::include lines),
clauses/*.md and clauses/media/*, in the Markdown flavour of the ETSI CTI
toolchain (forge.etsi.org/rep/cti/md-specs-dev): numbered ATX headings,
`> NOTE:` blockquotes, `<span id="_ref_i.n">` reference entries and
[\[i.n\]](#_ref_i.n) citations, `ABBR        expansion` entries, bold
figure and table captions, annexes `# Annex A (normative): …`, History
table. Uses documentation/ts.yaml like `saref-dev ts`.

The ontology annex reuses TSGenerator.describe_* with the Word
primitives redirected to Markdown.

Tested on saref4inma with the ETSI Docker images (processMDSpec,
pandocFilter, pandoc, update_format_styles): Word document with figures,
tables, NOTE and EW styles.
parent 58c879e5

README.md

+23 −0
Changes for README.md: 23 added lines, 0 removed lines.
Original line number Diff line number Diff line
@@ -148,6 +148,29 @@ annexes: # in order 
  - file: bibliography.md

```



## Markdown Technical Specification (branch `md-specs-dev`, experimental)



`saref-dev md` writes the TS as Markdown in the flavour of the ETSI CTI toolchain [md-specs-dev](https://forge.etsi.org/rep/cti/md-specs-dev/specification-example), in `target/md/`: a master file `TS-<number>.md` (YAML front matter + `::include` lines), one file per clause in `clauses/`, the figures in `clauses/media/`. The same `documentation/ts.yaml` as `saref-dev ts` applies. The ontology annex reuses the DOCX generator (`TSGenerator.describe_*`) with the Word primitives redirected to Markdown.



The ETSI toolchain then produces the Word document (and, in a GitLab project using the `specification-example` pipeline, the website and release notes). Locally, with Docker, from `target/md/`:



```

MT=forge.etsi.org:5050/cti/md-specs-dev/tools/markdowntools:master

GB=forge.etsi.org:5050/cti/md-specs-dev/tools/generatebaseline:watermark

PD=forge.etsi.org:5050/cti/md-specs-dev/tools/generatebaseline/pandoc:master

f=TS-103410-5.md

docker run --rm -v $(pwd):/tmp/ -u $(id -u):$(id -g) -w /tmp $MT processMDSpec -fmo $f -fmf frontmatter.md

docker run --rm -v $(pwd):/tmp/ -u $(id -u):$(id -g) -w /tmp $MT processMDSpec $f > spec.md

docker run --rm -v $(pwd):/tmp/ -u $(id -u):$(id -g) $GB pandocFilter -ts -fp -o /tmp/ /tmp/spec.md

docker run --rm -v $(pwd):/data -u $(id -u):$(id -g) -w /data $PD /data/spec.md -F mermaid-filter -F plantuml-filter \

  -f markdown+escaped_line_breaks -t docx --reference-doc /data/ts_spec_template.docx -o spec.docx

docker run --rm -v $(pwd):/tmp/ -u $(id -u):$(id -g) -w /tmp $GB update_format_styles spec.docx spec_styled.docx

```



(`ts_spec_template.docx` and the cover step `forgelib-baseline ts_cover_skeleton.docx frontmatter.md spec.docx` come from `specification-example/pipeline-scripts/`; the cover skeleton there is an ISG one and needs a SmartM2M TS variant.)



Known gaps: the ontology annex lines (`IRI:`, `definition:`, …) are plain paragraphs, not the ETSI `EW` style; HTML sources (`references.html`) are converted roughly; SVG figures need a PNG next to them.



## About



The SAREF pypeline is part of the SAREF Development Framework. The following projects contributed to the SAREF Pipeline:

src/saref_pypeline/__main__.py

+7 −0
Changes for src/saref_pypeline/__main__.py: 7 added lines, 0 removed lines.
Original line number Diff line number Diff line
@@ -135,6 +135,13 @@ def build_parser(): 
        description="Generate the Technical Specification (DOCX) for a SAREF project.",

        epilog="This command require extra 'ts', install with uv tool install 'saref-pypeline[ts]'",

    )

    subparsers.add_parser(

        "md",

        parents=[common_arguments, sources_arguments],

        help="Experimental - Generate the Technical Specification as Markdown in the ETSI md-specs-dev flavour.",

        description="Experimental - Generate the Technical Specification as Markdown (target/md/), to be converted to DOCX by the ETSI md-specs-dev toolchain (https://forge.etsi.org/rep/cti/md-specs-dev).",

        epilog="This command require extra 'ts', install with uv tool install 'saref-pypeline[ts]'",

    )

    subparsers.add_parser(

        "ts2md",

        parents=[common_arguments, sources_arguments],

src/saref_pypeline/constants.py

+1 −0
Changes for src/saref_pypeline/constants.py: 1 added line, 0 removed lines.
Original line number Diff line number Diff line
@@ -30,6 +30,7 @@ class PipelineMode(Enum): 
    WEBSITE = "website"

    TS = "ts"

    TS2MD = "ts2md"

    MD = "md"





class TargetType(Enum):

src/saref_pypeline/md/__init__.py

0 → 100644
+1 −0
Changes for src/saref_pypeline/md/__init__.py: 1 added line, 0 removed lines.
Original line number Diff line number Diff line 
from saref_pypeline.md.md_generator import MDGenerator

src/saref_pypeline/md/md_generator.py

0 → 100644
+701 −0

File added.

Preview size limit exceeded, changes collapsed.