From b0213f0265dd24cfacdf6ad820a692f4de9643e6 Mon Sep 17 00:00:00 2001 From: Michele Carignani <michele.carignani@etsi.org> Date: Sun, 29 Nov 2020 11:45:27 +0100 Subject: [PATCH] improve documentation --- src/templates/doc2tosca-details.html | 30 ++++++++++++++-------------- src/templates/doc2tosca-details.md | 21 +++++++++++++++---- src/templates/home.html | 1 + 3 files changed, 33 insertions(+), 19 deletions(-) diff --git a/src/templates/doc2tosca-details.html b/src/templates/doc2tosca-details.html index 6e49aa9..d51d48b 100644 --- a/src/templates/doc2tosca-details.html +++ b/src/templates/doc2tosca-details.html @@ -33,33 +33,33 @@ </h4> <p>The tool works as follows:</p> - -<p>Step 1: In the uploaded Document it searches for headings equal to:</p> - +<h2 id="step-1-uploading-the-files">Step 1: Uploading the files</h2> +<p>In the uploaded Document it searches for headings equal to:</p> <ul> -<li><code>6 VNFD TOSCA model</code></li> -<li><code>7 NSD TOSCA model</code></li> -<li><code>8 PNFD TOSCA model</code>,</li> -<li><code>9 Common Definitions</code>,</li> +<li><code>6\tVNFD TOSCA model</code></li> +<li><code>7\tNSD TOSCA model</code></li> +<li><code>8\tPNFD TOSCA model</code>,</li> +<li><code>9\tCommon Definitions</code>,</li> </ul> - -<p>Step 2: For each of the section after the heading (and until the next heading is found), the tool searches for tables with the following properties:</p> - +<h2 id="step-2-generation-of-data-types">Step 2, generation of data types</h2> +<p>For each of the section after the heading the tool searches for tables with the following properties:</p> <ul> <li>It contains only one cell (i.e. one row and one column) and</li> <li>the content matches the regular expression <code>^tosca\.[a-zA-Z\.:0-9\s]*$</code>, i.e. the text starts with <code>tosca.</code> and contains letters, numbers, <code>:</code> or white space.</li> </ul> - -<p>Step 3: The four sets of generated definitions are written to files named:</p> - +<h2 id="step-3-generation-of-examples">Step 3, generation of examples</h2> +<p>Within Annex A, each example is identified by a set of lines starting with <code>tosca_definitions_version</code>. If the last text line before the start of the example contains the name of a YAML file, that name is used to name the generated file for the example. Otherwise a incremented, 2-digit integer number is used. Filename is prepended with the number of the clause where the example is found.</p> +<h2 id="step-4-generation-of-files">Step 4: Generation of files</h2> +<p>The four sets of generated definitions and all identified Annex A examples are written to files named:</p> <ul> <li><code>generated_etsi_nfv_sol001_vnfd_types.yaml</code></li> <li><code>generated_etsi_nfv_sol001_nsd_types.yaml</code></li> <li><code>generated_etsi_nfv_sol001_pnfd_types.yaml</code></li> <li><code>generated_etsi_nfv_sol001_common_types.yaml</code></li> +<li><code>example_<clause>_<examplename>.yaml</code></li> </ul> - -<p>Step 4: The files are archived in a zip file named <code>tosca_defs.zip</code> which is served as a response.</p> +<h2 id="step-5-download">Step 5: Download</h2> +<p>The files are archived in a zip file named <code>tosca_defs.zip</code> which is served as a response.</p> <center> <p> diff --git a/src/templates/doc2tosca-details.md b/src/templates/doc2tosca-details.md index 3449b22..903cd71 100644 --- a/src/templates/doc2tosca-details.md +++ b/src/templates/doc2tosca-details.md @@ -1,23 +1,36 @@ The tool works as follows: -Step 1: In the uploaded Document it searches for headings equal to: +## Step 1: Uploading the files + +In the uploaded Document it searches for headings equal to: * `6\tVNFD TOSCA model` * `7\tNSD TOSCA model` * `8\tPNFD TOSCA model`, * `9\tCommon Definitions`, -Step 2: For each of the section after the heading (and until the next heading is found), the tool searches for tables with the following properties: +## Step 2, generation of data types + +For each of the section after the heading the tool searches for tables with the following properties: * It contains only one cell (i.e. one row and one column) and * the content matches the regular expression `^tosca\.[a-zA-Z\.:0-9\s]*$`, i.e. the text starts with `tosca.` and contains letters, numbers, `:` or white space. -Step 3: The four sets of generated definitions are written to files named: +## Step 3, generation of examples + +Within Annex A, each example is identified by a set of lines starting with `tosca_definitions_version`. If the last text line before the start of the example contains the name of a YAML file, that name is used to name the generated file for the example. Otherwise a incremented, 2-digit integer number is used. Filename is prepended with the number of the clause where the example is found. + +## Step 4: Generation of files + +The four sets of generated definitions and all identified Annex A examples are written to files named: * `generated_etsi_nfv_sol001_vnfd_types.yaml` * `generated_etsi_nfv_sol001_nsd_types.yaml` * `generated_etsi_nfv_sol001_pnfd_types.yaml` * `generated_etsi_nfv_sol001_common_types.yaml` +* `example_<clause>_<examplename>.yaml` + +## Step 5: Download -Step 4: The files are archived in a zip file named `tosca_defs.zip` which is served as a response. +The files are archived in a zip file named `tosca_defs.zip` which is served as a response. diff --git a/src/templates/home.html b/src/templates/home.html index 32dc777..36a6167 100644 --- a/src/templates/home.html +++ b/src/templates/home.html @@ -106,6 +106,7 @@ For any other inquiry, contact <a href="mailto:cti_support@etsi.org">ETSI CTI</a </div> <center> + <p><a href="https://labs.etsi.org/rep/cti-tools/tosca2doc">Source code</a></p> <small>Copyright © ETSI 2019. All rights reserved.</small> </center> </body> -- GitLab