software-versions-processor.../docs/index.rst

68 lines
3.2 KiB
ReStructuredText
Raw Normal View History

2023-08-30 18:03:06 +02:00
#############################
Software Artifact Processor
#############################
2023-08-30 17:40:36 +02:00
This library has been initially designed to deposit software artifacts programmatically in Zenodo.
It is actually a general-purpose library capable of analyzing a list of
2023-08-30 18:03:06 +02:00
software artifacts (represented by the metadata) and process them.
2023-08-30 17:40:36 +02:00
2023-08-30 18:03:06 +02:00
The library currently offers two processors:
2023-08-30 17:40:36 +02:00
* **ZenodoExporter**: deposit the software artifact in Zenodo obtaining a DOI;
* **BibLaTeXExporter**: export the software artifact in a ``bib`` file using the BibLaTeX format.
2023-08-30 18:03:06 +02:00
Other processors can be easily added in the future by extending the ``SoftwareArtifactProcessor`` class.
2023-08-30 17:40:36 +02:00
2023-08-30 18:35:06 +02:00
The core class of the library is ``Analyser``, which must be initialized with:
2023-08-30 17:40:36 +02:00
* a configuration (JSON Object);
* a list of software artifacts described by their metadata (JSON Array).
2023-08-30 18:35:06 +02:00
The configuration must contain at least the list of exporters to be used and their configuration parameters.
Exporter configuration requires at least the ``elaboration`` property, which can assume the following values
2023-08-30 17:40:36 +02:00
(see ``ElaborationType`` enumerated):
* **ALL**: The exporter analyses all the software artifacts;
2023-08-30 18:35:06 +02:00
* **UPDATE_ONLY**: The exporter analyes only the software artifact to be updated in the target;
* **NEW**: The exporter analyses only the software artifact that does not yet exist in the target;
2023-08-30 17:40:36 +02:00
* **NONE**: Does not export the software artifact in the target, but each software artifact is elaborated for the exporting without effectively doing it. It is a dry run.
2023-08-30 18:35:06 +02:00
The processors are executed in the order they are defined.
A processor could produce metadata itself (e.g., the obtained Zenodo DOI).
The input metadata + the metadata generated by a processor are made available to the subsequent processor.
2023-08-30 17:40:36 +02:00
2023-08-30 18:35:06 +02:00
At the end of the processing phase, the library produces the actualized output of all the software artifact metadata.
2023-08-30 17:40:36 +02:00
2023-08-30 18:35:06 +02:00
Moreover, the configuration can optionally include an arbitrary set of metadata used as default metadata for all software artifacts defined in the list.
2023-08-30 17:40:36 +02:00
2023-08-30 18:35:06 +02:00
The list of software artifacts contains an arbitrary set of metadata.
It depends on the processor using certain metadata, among others.
2023-08-30 17:40:36 +02:00
2023-08-30 18:35:06 +02:00
While analyzing each software artifact, the ``Analyser`` link it with the previously elaborated software artifact.
Relating an artifact with the previous one is helpful if a processor needs to link them in some way.
It is in charge of the processor's logic of connecting them using specific metadata values used as conditions.
2023-08-30 17:40:36 +02:00
2023-08-30 18:35:06 +02:00
The library dynamically calculates the value of metadata of a software artifact using the following features:
2023-08-30 17:40:36 +02:00
* A property can contain the value of another property indicated as a variable using the referred property name;
* The library merges the metadata of the software artifact with the metadata defined in the configuration;
* The library calculates the final metadata values, replacing the variables only after merging the properties.
The following example show an example of configuration
.. literalinclude:: ../src/test/resources/gcat-test-sandbox.json
2023-08-30 18:35:06 +02:00
:language: JSON
..
The output of the elaboration is the following
.. literalinclude:: ./gcat/gcat.json
:language: JSON
The output generated by ``BibLaTeXExporter`` is
.. literalinclude:: ./gcat/gcat.bib
:language: bib