Merge pull request #43 from Materials-Data-Science-and-Informatics/dev

Some fixes, added metadata, added `publication_author` flag, added `somesy fill` command

Author: apirogov

.pre-commit-config.yaml

@@ -82,9 +82,16 @@ repos:
     - repo: local
       hooks:
         # NOTE: copy from .pre-commit-hooks.yaml, for technical reasons
-        - id: somesy
-          name: somesy
+        - id: somesy-sync
+          name: Run somesy sync
           entry: somesy sync
           language: python
           files: '^\.somesy\.toml|pyproject\.toml$'
           pass_filenames: false
+
+        - id: somesy-fill
+          name: Update AUTHORS.md
+          entry: somesy fill -t docs/_template_authors.md -o AUTHORS.md
+          language: python
+          files: '^\.somesy\.toml|pyproject\.toml$'
+          pass_filenames: false

.pre-commit-hooks.yaml

@@ -1,7 +1,8 @@
 - id: somesy
   name: somesy
   description: Sync your metadata files with somesy
-  entry: somesy sync
+  entry: somesy
+  args: ["sync"]
   language: python
   files: '^somesy\.toml|\.somesy\.toml|pyproject\.toml|package\.json$'
   pass_filenames: false

.somesy.toml

@@ -13,7 +13,7 @@ given-names = "Mustafa"
 email = "m.soylu@fz-juelich.de"
 orcid = "https://orcid.org/0000-0003-2637-0432"
 
-contribution = "The main developer, maintainer and tester."
+contribution = "Main developer, maintainer and tester."
 contribution_begin = "2023-03-01"
 contribution_types = ["maintenance", "code", "test", "review", "doc"]
 
@@ -26,7 +26,7 @@ given-names = "Anton"
 email = "a.pirogov@fz-juelich.de"
 orcid = "https://orcid.org/0000-0002-5077-7497"
 
-contribution = "Initial concepts, tool development and enhancement, documentation."
+contribution = "Concepts, tool development and enhancement, documentation."
 contribution_begin = "2023-03-01"
 contribution_types = ["ideas", "code", "test", "review", "doc"]
 
@@ -38,10 +38,34 @@ given-names = "Jens"
 email = "j.broeder@fz-juelich.de"
 orcid = "https://orcid.org/0000-0001-7939-226X"
 
-contribution = "Valuable input concerning metadata standards and usability."
+contribution = "Discussions and suggestions concerning metadata standards and usability."
 contribution_begin = "2023-03-01"
+contribution_end = "2023-03-31"
 contribution_types = ["ideas"]
 
+[[project.people]]
+family-names = "Hofmann"
+given-names = "Volker"
+email = "v.hofmann@fz-juelich.de"
+orcid = "https://orcid.org/0000-0002-5149-603X"
+
+contribution = "Discussions and suggestions concerning tool scope and usability."
+contribution_begin = "2023-06-01"
+contribution_end = "2023-06-30"
+contribution_types = ["ideas"]
+
+publication_author = true
+
+[[project.people]]
+family-names = "Sandfeld"
+given-names = "Stefan"
+email = "s.sandfeld@fz-juelich.de"
+orcid = "https://orcid.org/0000-0001-9560-4728"
+
+contribution_types = ["fundingFinding"]
+
+publication_author = true
+
 [config]
 no_sync_cff = false
 cff_file = "CITATION.cff"

AUTHORS.md

@@ -1,38 +1,42 @@
 # Authors and Contributors
 
-**Main authors** are persons whose contributions significantly shaped
-the state of the software at some point in time.
+**Authors** are people whose contributions significantly shaped
+the state of `somesy` at some point in time.
 
-**Additional contributors** are persons who are not main authors,
-but contributed non-trivially to this project,
-e.g. by providing smaller fixes and enhancements to the code and/or documentation.
+**Additional contributors** are people who contributed non-trivially to this project
+in different ways, e.g. by providing smaller fixes and enhancements to the code
+and/or documentation.
 
 Of course, this is just a rough overview and categorization.
 For a more complete overview of all contributors and contributions,
 please inspect the git history of this repository.
 
-## Main Authors
+## Authors
 
 - Mustafa Soylu (
   [E-Mail](mailto:m.soylu@fz-juelich.de),
   [ORCID](https://orcid.org/0000-0003-2637-0432)
-  ): original author
-
+  ): Main developer, maintainer and tester.
 - Anton Pirogov (
   [E-Mail](mailto:a.pirogov@fz-juelich.de),
   [ORCID](https://orcid.org/0000-0002-5077-7497)
-  ): documentation, review, and ideas
+  ): Concepts, tool development and enhancement, documentation.
 
-## Additional Contributors
 
-<!--
-- Name (E-mail, ORCID):
-Summary of contribution
--->
+## Additional Contributors
 
 - Jens Bröder (
   [E-Mail](mailto:j.broeder@fz-juelich.de),
   [ORCID](https://orcid.org/0000-0001-7939-226X)
-  ): ideas
-
-... maybe **[you](https://materials-data-science-and-informatics.github.io/somesy/main/contributing)**?
+  ): Discussions and suggestions concerning metadata standards and usability.
+- Volker Hofmann (
+  [E-Mail](mailto:v.hofmann@fz-juelich.de),
+  [ORCID](https://orcid.org/0000-0002-5149-603X)
+  ): Discussions and suggestions concerning tool scope and usability.
+- Stefan Sandfeld (
+  [E-Mail](mailto:s.sandfeld@fz-juelich.de),
+  [ORCID](https://orcid.org/0000-0001-9560-4728)
+  )
+
+
+... maybe **[you](https://materials-data-science-and-informatics.github.io/somesy/latest/contributing)**?

CITATION.cff

@@ -11,14 +11,22 @@ keywords:
 - metadata
 - FAIR
 authors:
-- email: m.soylu@fz-juelich.de
-  family-names: Soylu
+- orcid: https://orcid.org/0000-0003-2637-0432
+  email: m.soylu@fz-juelich.de
   given-names: Mustafa
-  orcid: https://orcid.org/0000-0003-2637-0432
+  family-names: Soylu
+- email: v.hofmann@fz-juelich.de
+  orcid: https://orcid.org/0000-0002-5149-603X
+  family-names: Hofmann
+  given-names: Volker
+- email: s.sandfeld@fz-juelich.de
+  orcid: https://orcid.org/0000-0001-9560-4728
+  family-names: Sandfeld
+  given-names: Stefan
 - email: a.pirogov@fz-juelich.de
+  orcid: https://orcid.org/0000-0002-5077-7497
   family-names: Pirogov
   given-names: Anton
-  orcid: https://orcid.org/0000-0002-5077-7497
 contact:
 - email: m.soylu@fz-juelich.de
   family-names: Soylu

README.md

@@ -71,7 +71,7 @@ keywords = ["some", "descriptive", "keywords"]
 license = "MIT"
 repository = "https://github.com/username/my-amazing-project"
 
-# This is you, the proud author of your project
+# This is you, the proud author of your project:
 [[project.people]]
 given-names = "Jane"
 family-names = "Doe"
@@ -80,12 +80,14 @@ orcid = "https://orcid.org/0000-0000-0000-0001"
 author = true      # is a full author of the project (i.e. appears in citations)
 maintainer = true  # currently maintains the project (i.e. is a contact person)
 
-# this person is a acknowledged contributor, but not author or maintainer:
+# this person is an acknowledged contributor, but not author or maintainer:
 [[project.people]]
 given-names = "Another"
 family-names = "Contributor"
 email = "a.contributor@example.com"
 orcid = "https://orcid.org/0000-0000-0000-0002"
+# ... but for scientific publications, this contributor should be listed as author:
+publication_author = true
 
 [config]
 verbose = true     # show detailed information about what somesy is doing
@@ -151,17 +153,16 @@ Here is an overview of all the currently supported files and formats.
 | Input Formats  | Status | | Target Formats                | Status |
 | -------------- | ------ |-| ----------------------------- | ------ |
 | (.)somesy.toml | ✓      | | pyproject.toml _(poetry)_     | ✓      |
-| pyproject.toml | ✓(1.)  | | pyproject.toml _(setuptools)_ | ✓(2.)  |
-| package.json   | ✓      | | package.json                  | ✓(3.)  |
+| pyproject.toml | ✓      | | pyproject.toml _(setuptools)_ | ✓(1.)  |
+| package.json   | ✓      | | package.json                  | ✓(2.)  |
 |                |        | | CITATION.cff                  | ✓      |
-|                |        | | codemeta.json                 | ✓(4.)  |
+|                |        | | codemeta.json                 | ✓(3.)  |
 
 **Notes:**
 
-1. information must be placed inside a `tool.somesy` section (as explained above)
-2. note that `somesy` does not support setuptools *dynamic fields*
-3. `package.json` only supports one author, so `somesy` will pick the *first* listed author
-4. unlike other targets, `somesy` will *re-create* the `codemeta.json` (i.e. do not edit it by hand!)
+1. note that `somesy` does not support setuptools *dynamic fields*
+2. `package.json` only supports one author, so `somesy` will pick the *first* listed author
+3. unlike other targets, `somesy` will *re-create* the `codemeta.json` (i.e. do not edit it by hand!)
 
 <!-- --8<-- [end:quickstart] -->
 

codemeta.json

@@ -25,6 +25,18 @@
             "familyName": "Soylu",
             "givenName": "Mustafa"
         },
+        {
+            "@id": "https://orcid.org/0000-0002-5149-603X",
+            "@type": "Person",
+            "familyName": "Hofmann",
+            "givenName": "Volker"
+        },
+        {
+            "@id": "https://orcid.org/0000-0001-9560-4728",
+            "@type": "Person",
+            "familyName": "Sandfeld",
+            "givenName": "Stefan"
+        },
         {
             "@id": "https://orcid.org/0000-0002-5077-7497",
             "@type": "Person",
@@ -49,14 +61,14 @@
             "identifier": "'version':",
             "name": "'version':",
             "runtimePlatform": "Python 3",
-            "version": "'^0.7.0'}"
+            "version": "'^1.9.2'}"
         },
         {
             "@type": "SoftwareApplication",
             "identifier": "'version':",
             "name": "'version':",
             "runtimePlatform": "Python 3",
-            "version": "'^1.9.2'}"
+            "version": "'^0.7.0'}"
         },
         {
             "@type": "SoftwareApplication",
@@ -79,6 +91,13 @@
             "runtimePlatform": "Python 3",
             "version": "^4.11.0"
         },
+        {
+            "@type": "SoftwareApplication",
+            "identifier": "jinja2",
+            "name": "jinja2",
+            "runtimePlatform": "Python 3",
+            "version": "^3.1.2"
+        },
         {
             "@type": "SoftwareApplication",
             "identifier": "packaging",

docs/_template_authors.md

@@ -0,0 +1,35 @@
+# Authors and Contributors
+
+**Authors** are people whose contributions significantly shaped
+the state of `{{ project.name }}` at some point in time.
+
+**Additional contributors** are people who contributed non-trivially to this project
+in different ways, e.g. by providing smaller fixes and enhancements to the code
+and/or documentation.
+
+Of course, this is just a rough overview and categorization.
+For a more complete overview of all contributors and contributions,
+please inspect the git history of this repository.
+
+## Authors
+
+{% for p in project.authors() %}
+{%- set contr_desc = p.contribution or "" -%}
+- {{ p.full_name }} (
+  [E-Mail](mailto:{{ p.email }}),
+  [ORCID]({{ p.orcid }})
+  ){{ ": "+contr_desc if contr_desc else "" }}
+{% endfor %}
+
+## Additional Contributors
+
+{% for p in project.contributors() %}
+{%- set contr_desc = p.contribution or "" -%}
+- {{ p.full_name }} (
+  [E-Mail](mailto:{{ p.email }}),
+  [ORCID]({{ p.orcid }})
+  ){{ ": "+contr_desc if contr_desc else "" }}
+{% endfor %}
+
+... maybe **[you](https://materials-data-science-and-informatics.github.io/somesy/latest/contributing)**?
+

docs/manual.md

@@ -387,6 +387,37 @@ target is enabled, `somesy` will generate your `codemeta.json` by:
 As `codemeta.json` is considered a technical "backend-format" derived from other
 inputs, in most cases you probably do not need or should edit it by hand anyway.
 
+## Using somesy to insert metadata into project documentation
+
+While `somesy` can synchronize structured metadata files and formats, there is a common case that cannot be covered by the `sync` command - when project metadata should appear in plain text documents, such as documentation files and web pages.
+
+As for documentation the needs and used tooling in different projects is vastly different, `somesy` provides a very general solution to this problem
+with the `fill` command. It takes a
+[Jinja2](https://jinja.palletsprojects.com/en/3.1.x/)
+template and returns the resulting file where the project metadata is inserted the form dictated by the template.
+
+For example, a template is used to generate the
+[`AUTHORS.md`](https://github.com/Materials-Data-Science-and-Informatics/somesy/blob/main/AUTHORS.md)
+file in the somesy repository, which is also shown as the
+[Credits](./credits.md) page, using the following command:
+
+```shell
+somesy fill docs/_template_authors.md -o AUTHORS.md
+```
+
+??? example "_template_authors.md"
+    ```
+    --8<-- "docs/_template_authors.md"
+    ```
+
+??? example "AUTHORS.md"
+    ```
+    --8<-- "AUTHORS.md"
+    ```
+
+The template gets the complete
+[ProjectMetadata](reference/somesy/core/models.md#somesy.core.models.ProjectMetadata) as its context, so it is possible to access all included project and contributor information.
+
 ## FAQ
 
 ### Somesy introduces it's own metadata format... isn't this counter-productive?
@@ -406,3 +437,21 @@ hood, you use `somesy` (or anything like it) or not - they can use the
 corresponding files they already know to get the information they need.
 So there is no "risk" involved in adopting `somesy`, because it does not try to
 abolish any other formats or standards or becoming such.
+
+### In my project, the effective authors and the publication authors are not the same! What to do?
+
+The `author` flag in `somesy` is intended to mark people who significantly contributed
+to the project in a hands-on way and are closely familiar with details, i.e. can answer
+specific questions. A reason to stick with this strict understanding of "author"
+is that a user will be usually interested in contacting such a person to help
+them with problems.
+
+However, we are aware that acknowledgement practices in different scientific
+communities vary and current practices in academic publication do not allow for
+sufficiently granular distinction of contributor roles.
+Even though the proper solution to problem would be improving community practices,
+`somesy` supports the `publication_author` flag, that can be set independently of the
+`author` flag and will make sure that certain contributors **will** appear as authors
+in an academic citation context (i.e. reflected in the `CITATION.cff` file, which can be
+used for [Zenodo publications](https://docs.software-metadata.pub/en/latest/tutorials/automated-publication-with-ci.html)), but **will not** appear as authors in a technical context
+(such as the metadata in a software registry like [PyPI](https://pypi.org)).

mkdocs.yml

@@ -143,6 +143,9 @@ plugins:
       enabled: !ENV [OFFLINE, false]
   # to make multi-version docs work right
   - mike
+  - exclude:
+      glob:
+        - "_*.md"  # for internal purposes
 
 hooks:
   - docs/scripts/coverage_status.py