Merge branch 'main' into feature/consistent_pydantic

Author: mustafasoylu

.somesy.toml

@@ -49,7 +49,7 @@ no_sync_pyproject = false
 pyproject_file = "pyproject.toml"
 no_sync_codemeta = false
 codemeta_file = "codemeta.json"
-sync_package_json = false
+no_sync_package_json = true
 show_info = false
 verbose = false
 debug = false

CHANGELOG.md

@@ -4,7 +4,6 @@ Here we provide notes that summarize the most important changes in each released
 
 Please consult the changelog to inform yourself about breaking changes and security issues.
 
-## [v0.1.0](https://github.com/Materials-Data-Science-and-Informatics/somesy/tree/v0.1.0) <small>(2023-05-12)</small> { id="0.1.0" }
+## [v0.1.0](https://github.com/Materials-Data-Science-and-Informatics/somesy/tree/v0.1.0) <small>(2023-08-10)</small> { id="0.1.0" }
 
 * First release
-

README.md

@@ -58,8 +58,9 @@ Yes, somesy is *another* tool with its own configuration. However, for your
 project metadata it is hopefully the last file you need, and the only one you
 have to think about, `somesy` will take care of the others for you!
 
-To get started, create a file named `somesy.toml` (or `.somesy.toml`):
+To get started, create a file named `somesy.toml`:
 
+<!-- --8<-- [start:somesytoml] -->
 ```toml
 [project]
 name = "my-amazing-project"
@@ -89,8 +90,10 @@ orcid = "https://orcid.org/0000-0000-0000-0002"
 [config]
 verbose = true     # show detailed information about what somesy is doing
 ```
+<!-- --8<-- [end:somesytoml] -->
 
-If you happen to work on a Python project and use a `pyproject.toml`, you can also put this information there and avoid having another separate file.  In that case, simply prepend `tool.somesy` to the names of all sections (i.e.  `[project]` becomes `[tool.somesy.project]`).
+Alternatively, you can also add the somesy configuration to an existing
+`pyproject.toml` or `package.json` file. The somesy [manual](https://materials-data-science-and-informatics.github.io/somesy/main/manual/#somesy-input-file) contains examples showing how to do that.
 
 ### Using somesy
 
@@ -111,7 +114,9 @@ By default, `somesy` will create (if they did not exist) or update `CITATION.cff
 You can see call available options with `somesy --help`,
 all of these can also be conveniently set in your `somesy.toml` file.
 
-### Setting up somesy as a pre-commit hook
+### Somesy as a pre-commit hook
+
+<!-- --8<-- [start:precommit] -->
 
 We highly recommend to use `somesy` as a [pre-commit hook](https://pre-commit.com/).
 A pre-commit hook runs on every commit to automatically point out issues or fix them on the spot,
@@ -137,24 +142,26 @@ so when using `somesy` with pre-commit, keep in mind that
 * if `somesy` changed some files, you need to `git add` them again (and rerun pre-commit)
 * if you explicitly run `pre-commit`, make sure to `git add` all changed files (just like before a commit)
 
+<!-- --8<-- [end:precommit] -->
+
 ## Supported File Formats
 
 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                  | ✓      |
-|                |        | | mkdocs.yml                    | TBD    |
+| (.)somesy.toml | ✓      | | pyproject.toml _(poetry)_     | ✓      |
+| pyproject.toml | ✓(1.)  | | pyproject.toml _(setuptools)_ | ✓(2.)  |
+| package.json   | ✓      | | package.json                  | ✓(3.)  |
 |                |        | | CITATION.cff                  | ✓      |
-|                |        | | codemeta.json                 | ✓(3.)  |
+|                |        | | codemeta.json                 | ✓(4.)  |
 
 **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. unlike other targets, `somesy` will *re-create* the `codemeta.json` (i.e. you should not edit it by hand!)
+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!)
 
 <!-- --8<-- [end:quickstart] -->
 

docs/manual.md

@@ -16,6 +16,7 @@ metadata fields and can synchronize this information into different **target
 files**.
 
 !!! info
+
     The somesy schemas are designed to allow expressing metadata in the most
     useful and rich form, i.e. the best form that some of the target formats
     supports.
@@ -42,6 +43,7 @@ contribution of a person and acknowledge contributors that are neither full
 authors or maintainers.
 
 !!! note
+
     Currently, provided information about contributors that are neither authors
     nor maintainers, and all the detailed information on the contributions is
     not used.
@@ -110,28 +112,31 @@ The following tables sketch how fields are mapped to corresponding other fields
 some of the currently supported formats.
 
 === "Person Metadata"
-    | Field Name       | Poetry Config | SetupTools Config | CITATION.cff    | Requirement |
-    | ---------------- | ------------- | ----------------- | --------------- | ----------- |
-    | given-names      | name+email    | name              | given-names     | required    |
-    | family-names     | name+email    | name              | family-names    | required    |
-    | email            | name+email    | email             | email           | required    |
-    | orcid            | -             | -                 | orcid           | optional    |
-    | *(many others)*  | -             | -                 | *(same)*        | optional    |
+
+    | Field Name       | Poetry Config | SetupTools Config | CITATION.cff    | package.json | Requirement |
+    | ---------------- | ------------- | ----------------- | --------------- | ------------ | ----------- |
+    | given-names      | name+email    | name              | given-names     | name         | required    |
+    | family-names     | name+email    | name              | family-names    | name         | required    |
+    | email            | name+email    | email             | email           | email        | required    |
+    | orcid            | -             | -                 | orcid           | url          | optional    |
+    | *(many others)*  | -             | -                 | *(same)*        | -            | optional    |
 
 === "Project Metadata"
-    | Field Name        | Poetry Config | SetupTools Config | CITATION.cff    | Requirement |
-    | ----------------- | ------------- | ----------------- | --------------- | ----------- |
-    | name              | name          | name              | title           | required    |
-    | description       | description   | description       | abstract        | required    |
-    | license           | license       | license           | license         | required    |
-    | version           | version       | version           | version         | optional    |
-    |                   |               |                   |                 |             |
-    | *author=true*     | authors       | authors           | authors         | required    |
-    | *maintainer=true* | maintainers   | maintainers       | contact         | optional    |
-    |                   |               |                   |                 |             |
-    | keywords          | keywords      | keywords          | keywords        | optional    |
-    | repository        | repository    | urls.repository   | repository_code | optional    |
-    | homepage          | homepage      | urls.homepage     | url             | optional    |
+
+    | Field Name        | Poetry Config | SetupTools Config | CITATION.cff    | package.json | Requirement |
+    | ----------------- | ------------- | ----------------- | --------------- | ------------ | ----------- |
+    | name              | name          | name              | title           | name         | required    |
+    | description       | description   | description       | abstract        | description  | required    |
+    | license           | license       | license           | license         | license      | required    |
+    | version           | version       | version           | version         | version      | optional    |
+    |                   |               |                   |                 |              |             |
+    | *author=true*     | authors       | authors           | authors         | author       | required    |
+    | *maintainer=true* | maintainers   | maintainers       | contact         | maintainers  | optional    |
+    | *people*          | -             | -                 | -               | contributors | optional    |
+    |                   |               |                   |                 |              |             |
+    | keywords          | keywords      | keywords          | keywords        | keywords     | optional    |
+    | repository        | repository    | urls.repository   | repository_code | repository   | optional    |
+    | homepage          | homepage      | urls.homepage     | url             | homepage     | optional    |
 
 Note that the mapping is often not 1-to-1. For example, CITATION.cff allows rich
 specification of author contact information and complex names. In contrast,
@@ -158,26 +163,113 @@ Without an input file specifically provided, somesy will check if it can find a
 * `.somesy.toml`
 * `somesy.toml`
 * `pyproject.toml` (in `tool.somesy` section)
+* `package.json` (in `somesy` section)
 
 which is located in the current working directory. If you want to provide
 the somesy input file from a different location, you can pass it with the `-i` option.
 
+### Somesy Input File
+
+Here is an example how project metadata and `somesy` can be configured using
+one of the supported input formats:
+
+=== "somesy.toml"
+
+    --8<-- "README.md:somesytoml"
+
+=== "pyproject.toml"
+
+    ```toml
+    [tool.poetry]
+    name = "my-amazing-project"
+    version = "0.1.0"
+    ...
+
+    [tool.somesy.project]
+    name = "my-amazing-project"
+    version = "0.1.0"
+    description = "Brief description of my amazing software."
+
+    keywords = ["some", "descriptive", "keywords"]
+    license = "MIT"
+    repository = "https://github.com/username/my-amazing-project"
+
+    # This is you, the proud author of your project
+    [[tool.somesy.project.people]]
+    given-names = "Jane"
+    family-names = "Doe"
+    email = "j.doe@example.com"
+    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:
+    [[tool.somesy.project.people]]
+    given-names = "Another"
+    family-names = "Contributor"
+    email = "a.contributor@example.com"
+    orcid = "https://orcid.org/0000-0000-0000-0002"
+
+    [tool.somesy.config]
+    verbose = true     # show detailed information about what somesy is doing
+    ```
+
+=== "package.json"
+
+    ```json
+    {
+      "name": "my-amazing-project",
+      "version": "0.1.0",
+      ...
+
+      "somesy": {
+        "project": {
+          "name": "my-amazing-project",
+          "version": "0.1.0",
+          "description": "Brief description of my amazing software.",
+          "keywords": ["some", "descriptive", "keywords"],
+          "license": "MIT",
+          "repository": "https://github.com/username/my-amazing-project",
+          "people": [
+            {
+              "given-names": "Jane",
+              "family-names": "Doe",
+              "email": "j.doe@example.com",
+              "orcid": "https://orcid.org/0000-0000-0000-0001",
+              "author": true,
+              "maintainer": true
+            },
+            {
+              "given-names": "Another",
+              "family-names": "Contributor",
+              "email": "a.contributor@example.com",
+              "orcid": "https://orcid.org/0000-0000-0000-0002"
+            }
+          ]
+        },
+        "config": {
+          "verbose": true
+        }
+      }
+    }
+    ```
+
+All possible metadata fields and configuration options are explained further [above](#schemas-overview).
+
+### pre-commit hook
+
+--8<-- "README.md:precommit"
+
 ### Synchronization
 
 Unless configured otherwise, `somesy` will create `CITATION.cff`
 and `codemeta.json` files if they do not exist.
-Other supported files (such as `pyproject.toml`) are updated if they already
-exist in your repository.
+Other supported files (such as `pyproject.toml` or `package.json`)
+are updated if they already exist in your repository.
 
 If you do not want that somesy creates/synchronizes these files,
 you can disable them by CLI options or in your somesy configuration.
 
-### Somesy input file
-
-In the [quickstart](./quickstart.md) you can find an example somesy input file.
-
-All possible metadata fields and configuration options are explained further [above](#schemas-overview).
-
 ## Metadata Update Logic
 
 In this section we explain a few details about how `somesy` updates metadata.
@@ -195,14 +287,17 @@ In most cases, `somesy` will try not to interfere with other values, metadata
 and configuration you might have in a target file.
 
 !!! info
+
     For typically manually-edited files, it will even make sure that the
     comments stay in place! (currently works for TOML)
 
 !!! tip
+
     Only edit target files manually to add or update fields
     that `somesy` does **not** understand or care about!
 
 !!! warning
+
     All changes in target files you do to fields `somesy` *does* understand will be
     overwritten the next time you run somesy.
 
@@ -218,6 +313,7 @@ most cases, but in certain tricky situations it might not be able to figure out
 the and needed changes correctly.
 
 !!! danger
+
     Always check the files that somesy synchronized look right
     before committing/pushing the changes!
 
@@ -243,9 +339,11 @@ When somesy compares two metadata records about a person, it will proceed as fol
 3. Otherwise, the records are considered to be about the same person if they agree on the full name (i.e. given, middle and family name sequence).
 
 !!! tip
+
     State ORCIDs for persons whenever possible (i.e. the person has an ORCID)!
 
 !!! tip
+
     If a person does not have an ORCID, suggest that they should create one!
 
 Somesy will usually correctly understand cases such as:
@@ -259,6 +357,7 @@ Nevertheless, you should **check the changes somesy does** before committing the
 especially **after you significantly modified your project metadata**.
 
 !!! warning
+
     Note that changing the ORCID will not be recognized,
     because ORCIDs are assumed to be unique per person.
 
@@ -281,6 +380,7 @@ target is enabled, `somesy` will generate your `codemeta.json` by:
 * running `cffconvert` and `codemetapy` to combine both sources into a final `codemeta.json`
 
 !!! warning
+
     The `codemeta.json` is overwritten and regenerated from scratch every time you `sync`,
     so **do not edit it** if you have the codemeta target enabled in `somesy`!
 

docs/scripts/coverage_status.py

@@ -6,6 +6,7 @@
 import anybadge
 import pytest
 from coverage import Coverage
+from coverage.exceptions import NoSource
 from interrogate import badge_gen
 from interrogate.coverage import InterrogateCoverage
 
@@ -30,10 +31,14 @@ def on_pre_build(config):
     else:
         log.info("Using existing coverage data.")
 
-    cov = Coverage()
-    cov.load()
-    cov_percent = int(cov.report(file=StringIO()))
-    log.info(f"Test Coverage: {cov_percent}%, generating badge.")
+    cov_percent = 0
+    try:
+        cov_percent = get_coverage_percentage()
+    except NoSource:
+        # Source file is either deleted or moved, so we can't generate a badge, rerun the tests
+        log.info("Change in the source files, running pytest to collect.")
+        pytest.main(["--cov", "--cov-report=html"])
+        cov_percent = get_coverage_percentage()
 
     badge = anybadge.Badge(
         "coverage",
@@ -52,3 +57,13 @@ def on_pre_build(config):
     doc_cov = InterrogateCoverage(paths=["src"]).get_coverage()
     log.info(f"Docs Coverage: {doc_cov.perc_covered}%, generating badge.")
     badge_gen.create("docs", doc_cov)
+
+
+def get_coverage_percentage():
+    """Return the coverage percentage from the .coverage file."""
+    cov = Coverage()
+    cov.load()
+    cov_percent = cov.report(file=StringIO())
+    log.info(f"Test Coverage: {cov_percent}%, generating badge.")
+
+    return cov_percent