docs(xmllib): make args consistent (DEV-4314) (#1259)

dasch-swiss · Nov 7, 2024 · fb5f5a9 · fb5f5a9
1 parent 9b70810
commit fb5f5a9
Show file tree

Hide file tree

Showing 9 changed files with 72 additions and 60 deletions.
diff --git a/docs/xmllib-api-reference/value-converters.md b/docs/xmllib-api-reference/value-converters.md
@@ -0,0 +1 @@
+::: xmllib.value_converters
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -46,6 +46,7 @@ nav:
           - AudioSegmentResource: xmllib-api-reference/dsp-base-resources/audio-segment-resource.md
       - Configuration options: xmllib-api-reference/config-options.md
       - Value Checkers: xmllib-api-reference/value-checkers.md
+      - Value Converters: xmllib-api-reference/value-converters.md
       - Helpers: xmllib-api-reference/helpers.md
 
 theme:

diff --git a/src/dsp_tools/xmllib/__init__.py b/src/dsp_tools/xmllib/__init__.py
@@ -20,3 +20,7 @@
 from .value_checkers import is_nonempty_value as is_nonempty_value
 from .value_checkers import is_string_like as is_string_like
 from .value_checkers import is_timestamp as is_timestamp
+from .value_converters import convert_to_bool_string
+from .value_converters import replace_newlines_with_br_tags
+from .value_converters import replace_newlines_with_paragraph_tags
+from .value_converters import replace_newlines_with_tags
diff --git a/src/dsp_tools/xmllib/models/config_options.py b/src/dsp_tools/xmllib/models/config_options.py
@@ -23,9 +23,9 @@ class NewlineReplacement(Enum):
     """
     Options how to deal with `\\n` inside rich text values.
 
-    - `NONE`: Don't modify the rich text (`\\n` will be lost, because it is meaningless in an XML file)
-    - `PARAGRAPH`: Replace `Start\\nEnd` with `<p>Start</p><p>End</p>`
-    - `LINEBREAK`: Replace `Start\\nEnd` with `Start<br/>End`
+    - `NONE`: don't modify the rich text (`\\n` will be lost, because it is meaningless in an XML file)
+    - `PARAGRAPH`: replace `Start\\nEnd` with `<p>Start</p><p>End</p>`
+    - `LINEBREAK`: replace `Start\\nEnd` with `Start<br/>End`
     """
 
     NONE = auto()

diff --git a/src/dsp_tools/xmllib/models/dsp_base_resources.py b/src/dsp_tools/xmllib/models/dsp_base_resources.py
@@ -104,7 +104,7 @@ def add_comment_optional(self, comment: Any) -> AnnotationResource:
         If the value is not empty, add it as comment, otherwise return the resource unchanged.
 
         Args:
-            comment: Comment or empty value
+            comment: text or empty value
 
         Returns:
             The original resource, with the added comment
@@ -120,7 +120,7 @@ def add_migration_metadata(
         Add metadata from a SALSAH migration.
 
         Args:
-            creation_date: Creation date of the resource in SALSAH
+            creation_date: creation date of the resource in SALSAH
             iri: Original IRI in SALSAH
             ark: Original ARK in SALSAH
 
@@ -224,7 +224,7 @@ def add_comment(self, comment: str) -> RegionResource:
         Add a comment to the resource
 
         Args:
-            comment: Comment text
+            comment: text
 
         Returns:
             The original resource, with the added comment
@@ -237,7 +237,7 @@ def add_comment_multiple(self, comments: list[str]) -> RegionResource:
         Add several comments to the resource
 
         Args:
-            comments: List of comment texts
+            comments: list of texts
 
         Returns:
             The original resource, with the added comments
@@ -250,7 +250,7 @@ def add_comment_optional(self, comment: Any) -> RegionResource:
         If the value is not empty, add it as comment, otherwise return the resource unchanged.
 
         Args:
-            comment: Comment or empty value
+            comment: text or empty value
 
         Returns:
             The original resource, with the added comment
@@ -266,7 +266,7 @@ def add_migration_metadata(
         Add metadata from a SALSAH migration.
 
         Args:
-            creation_date: Creation date of the resource in SALSAH
+            creation_date: creation date of the resource in SALSAH
             iri: Original IRI in SALSAH
             ark: Original ARK in SALSAH
 
@@ -359,7 +359,7 @@ def add_comment(self, comment: str) -> LinkResource:
         Add a comment to the resource
 
         Args:
-            comment: Comment text
+            comment: text
 
         Returns:
             The original resource, with the added comment
@@ -372,7 +372,7 @@ def add_comment_multiple(self, comments: list[str]) -> LinkResource:
         Add several comments to the resource
 
         Args:
-            comments: List of comment texts
+            comments: list of texts
 
         Returns:
             The original resource, with the added comments
@@ -385,7 +385,7 @@ def add_comment_optional(self, comment: Any) -> LinkResource:
         If the value is not empty, add it as comment, otherwise return the resource unchanged.
 
         Args:
-            comment: Comment or empty value
+            comment: text or empty value
 
         Returns:
             The original resource, with the added comment
@@ -401,7 +401,7 @@ def add_migration_metadata(
         Add metadata from a SALSAH migration.
 
         Args:
-            creation_date: Creation date of the resource in SALSAH
+            creation_date: creation date of the resource in SALSAH
             iri: Original IRI in SALSAH
             ark: Original ARK in SALSAH
 
@@ -518,7 +518,7 @@ def add_title(self, title: str) -> VideoSegmentResource:
         Add a title to the resource.
 
         Args:
-            title: Title text
+            title: text
 
         Returns:
             The original resource, with the added title
@@ -533,7 +533,7 @@ def add_title_optional(self, title: Any) -> VideoSegmentResource:
         If the value is not empty, add it as title, otherwise return the resource unchanged.
 
         Args:
-            title: Title or empty value
+            title: text or empty value
 
         Returns:
             The original resource, with the added title
@@ -549,7 +549,7 @@ def add_comment(self, comment: str) -> VideoSegmentResource:
         Add a comment to the resource
 
         Args:
-            comment: Comment text
+            comment: text
 
         Returns:
             The original resource, with the added comment
@@ -562,7 +562,7 @@ def add_comment_multiple(self, comments: list[str]) -> VideoSegmentResource:
         Add several comments to the resource
 
         Args:
-            comments: List of comment texts
+            comments: list of texts
 
         Returns:
             The original resource, with the added comments
@@ -575,7 +575,7 @@ def add_comment_optional(self, comment: Any) -> VideoSegmentResource:
         If the value is not empty, add it as comment, otherwise return the resource unchanged.
 
         Args:
-            comment: Comment or empty value
+            comment: text or empty value
 
         Returns:
             The original resource, with the added comment
@@ -602,7 +602,7 @@ def add_description_multiple(self, descriptions: list[str]) -> VideoSegmentResou
         Add several descriptions to the resource
 
         Args:
-            descriptions: list of text
+            descriptions: list of texts
 
         Returns:
             The original resource, with the added descriptions
@@ -642,7 +642,7 @@ def add_keyword_multiple(self, keywords: list[str]) -> VideoSegmentResource:
         Add several keywords to the resource
 
         Args:
-            keywords: list of text
+            keywords: list of texts
 
         Returns:
             The original resource, with the added keywords
@@ -682,7 +682,7 @@ def add_relates_to_multiple(self, relates_to: list[str]) -> VideoSegmentResource
         Add several links to related resources
 
         Args:
-            relates_to: IDs of the related resources
+            relates_to: list of IDs of the related resources
 
         Returns:
             The original resource, with the added related resources
@@ -711,7 +711,7 @@ def add_migration_metadata(
         Add metadata from a SALSAH migration.
 
         Args:
-            creation_date: Creation date of the resource in SALSAH
+            creation_date: creation date of the resource in SALSAH
             iri: Original IRI in SALSAH
             ark: Original ARK in SALSAH
 
@@ -801,7 +801,7 @@ def add_title(self, title: str) -> AudioSegmentResource:
         Add a title to the resource.
 
         Args:
-            title: Title text
+            title: text
 
         Returns:
             The original resource, with the added title
@@ -816,7 +816,7 @@ def add_title_optional(self, title: Any) -> AudioSegmentResource:
         If the value is not empty, add it as title, otherwise return the resource unchanged.
 
         Args:
-            title: Title text or empty value
+            title: text or empty value
 
         Returns:
             The original resource, with the added title
@@ -832,7 +832,7 @@ def add_comment(self, comment: str) -> AudioSegmentResource:
         Add a comment to the resource
 
         Args:
-            comment: Comment text
+            comment: text
 
         Returns:
             The original resource, with the added comment
@@ -845,7 +845,7 @@ def add_comment_multiple(self, comments: list[str]) -> AudioSegmentResource:
         Add several comments to the resource
 
         Args:
-            comments: List of comment texts
+            comments: list of texts
 
         Returns:
             The original resource, with the added comments
@@ -858,7 +858,7 @@ def add_comment_optional(self, comment: Any) -> AudioSegmentResource:
         If the value is not empty, add it as comment, otherwise return the resource unchanged.
 
         Args:
-            comment: Comment or empty value
+            comment: text or empty value
 
         Returns:
             The original resource, with the added comment
@@ -885,7 +885,7 @@ def add_description_multiple(self, descriptions: list[str]) -> AudioSegmentResou
         Add several descriptions to the resource
 
         Args:
-            descriptions: list of text
+            descriptions: list of texts
 
         Returns:
             The original resource, with the added descriptions
@@ -925,7 +925,7 @@ def add_keyword_multiple(self, keywords: list[str]) -> AudioSegmentResource:
         Add several keywords to the resource
 
         Args:
-            keywords: list of text
+            keywords: list of texts
 
         Returns:
             The original resource, with the added keywords
@@ -965,7 +965,7 @@ def add_relates_to_multiple(self, relates_to: list[str]) -> AudioSegmentResource
         Add several links to related resources
 
         Args:
-            relates_to: IDs of the related resources
+            relates_to: list of IDs of the related resources
 
         Returns:
             The original resource, with the added related resources
@@ -994,7 +994,7 @@ def add_migration_metadata(
         Add metadata from a SALSAH migration.
 
         Args:
-            creation_date: Creation date of the resource in SALSAH
+            creation_date: creation date of the resource in SALSAH
             iri: Original IRI in SALSAH
             ark: Original ARK in SALSAH