Scripts project

This repository hosts some tools to automate some tasks on the Specifications group projects.

Generation of changemarks

The generation of a Word Change Request document is launched upon creation of a Merge Request. The generateChangemarks folder contains the following scripts:

• changemarks.py is in charge of generating a set of markdown files (one file per modified clause) containing the changes (additions and deletions) being made by the Merge Request. Additions are marked as underlined text and deletions as striked text.

• pandocFilter.py is in charge of adapting the markdown files (ToC references, figure captions and table captions) as required by Pandoc to be used as input.

• addTrackedChanges.py is in charge of converting the underlined and striked text in Word documents to tracked changes insertions and deletions respectively. It uses the Merge Request information to set the author and date of the changes.

All those scripts are dockerized into the same Docker image named generateChangemarks

How it works

The generateChangemarks.sh script implements the steps for the generation of the Word Change Request contribution document:

• Step 1. Generation of the set of markdown files containing the changes being made by a Merge Request BY changemarks.py.
• Step 2. Preparation of the markdown files for Pandoc to work properly pandocFilter.py.
• Step 3. Conversion of the markdown files to Word documents BY Pandoc.
  • Spec-template.docx is used as template for the conversion. It sets font style, headings styles, table and figure captions, etc...
• Step 4. Preparation of the Change Request Word document by combining the set of Word documents BY forgelib tool:
  • onem2m-coversheet-template.docx is used as template for the coversheet. It gets filled in by information from the Merge Request (Merge Request details and description)
  • onem2m-delimiter-start.docx and onem2m-delimiter-end.docx are the change delimiter template to be insertion between changes.
• Step 5. Additon of the tracked changes to the Change Request Word document BY addTrackedChanges.py.

Publication of specifications

The publication of specifications is meant to produce a Word document for a specific version (baseline) from the markdown specification file, which is launched upon creation of a tag.

How it works

The publish_spec.sh script implements the steps for the publication of a specification baseline:

• Step 1. Preparation of the markdown specification file for Pandoc to work properly BY pandocFilter.py.
• Step 2. Conversion of the markdown file to Word document BY Pandoc. The Word document is downloadable as an artifact of the corresponding tag pipeline.
  • Spec-template.docx is used as template for the conversion. It sets font style, headings styles, table and figure captions, etc...

Publication of specifications on Gitlab Pages

The publication of specifications on Gitlab Pages is meant to make the baseline Word specification documents easily accesible at https://specifications.onem2m.org/PROJECT/ Gitlab Pages URL. Upon the creation of a tag, if the publication of specification is successfull, the baseline specification will be published on the Gitlab Pages.

• updateIndex.py is in charge of updating index.html of the Gitlab Pages URL according to the CLEAN_WEB_PAGES variable.
• index.html is the home page of the Gitlab Pages URL. If it does not already exist, this file is used as template. Also, any modification of this file will make all projects Gitlab Pages to be updated to use the new template (already published baseline specifications are kept)

How it works

The publish_on_pages.sh script implements the steps for the publication of the baseline Word specification documents on Gitlab Pages.

The CLEAN_WEB_PAGES variable can be used to clean up the Gitlab Pages site:

• CLEAN_WEB_PAGES = false (default), the baseline Word specification document will be published on Gitlab Pages normally
• CLEAN_WEB_PAGES = true, the baseline Word specification document will be published on Gitlab Pages but ALL previous published documents will be removed (COMPLETE CLEAN-UP)
• CLEAN_WEB_PAGES = "TAG NAME", the baseline Word specification document version "TAG NAME" will be removed from Gitlab Pages. Note that no creation of tag is required in this case, a manual pipeline run is necessary with the CLEAN_WEB_PAGES variable properly set.

The upgrade_pages.sh script implements the upgrade of the index.html file in all Specification group project Gitlab Pages already being published. Upon an update of index.html, a pipeline for each project is triggered, and each project pipeline will recognise that an upgrade is necessary for the index.html, and it will run the publish_on_pages.sh script with a special value for TAG_NAME = "upgrade". An upgrade of the index.html is done without modifying the actual content of the Gitlab Pages.