Skip to content

Commit 2d3108d

Browse files
mustafasoylumustafasoylu
authored
Merge pull request #38 from Materials-Data-Science-and-Informatics/update_docs
Update docs for package.json
2 parents badccf9 + 3824f52 commit 2d3108d

10 files changed

Lines changed: 200 additions & 75 deletions

File tree

‎.somesy.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ no_sync_pyproject = false
4949
pyproject_file = "pyproject.toml"
5050
no_sync_codemeta = false
5151
codemeta_file = "codemeta.json"
52-
sync_package_json = false
52+
no_sync_package_json = true
5353
show_info = false
5454
verbose = false
5555
debug = false

‎CHANGELOG.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@ Here we provide notes that summarize the most important changes in each released
44

55
Please consult the changelog to inform yourself about breaking changes and security issues.
66

7-
## [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" }
7+
## [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" }
88

99
* First release
10-

‎README.md‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -58,8 +58,9 @@ Yes, somesy is *another* tool with its own configuration. However, for your
5858
project metadata it is hopefully the last file you need, and the only one you
5959
have to think about, `somesy` will take care of the others for you!
6060

61-
To get started, create a file named `somesy.toml` (or `.somesy.toml`):
61+
To get started, create a file named `somesy.toml`:
6262

63+
<!-- --8<-- [start:somesytoml] -->
6364
```toml
6465
[project]
6566
name = "my-amazing-project"
@@ -89,8 +90,10 @@ orcid = "https://orcid.org/0000-0000-0000-0002"
8990
[config]
9091
verbose = true # show detailed information about what somesy is doing
9192
```
93+
<!-- --8<-- [end:somesytoml] -->
9294

93-
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]`).
95+
Alternatively, you can also add the somesy configuration to an existing
96+
`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.
9497

9598
### Using somesy
9699

@@ -111,7 +114,9 @@ By default, `somesy` will create (if they did not exist) or update `CITATION.cff
111114
You can see call available options with `somesy --help`,
112115
all of these can also be conveniently set in your `somesy.toml` file.
113116

114-
### Setting up somesy as a pre-commit hook
117+
### Somesy as a pre-commit hook
118+
119+
<!-- --8<-- [start:precommit] -->
115120

116121
We highly recommend to use `somesy` as a [pre-commit hook](https://pre-commit.com/).
117122
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
137142
* if `somesy` changed some files, you need to `git add` them again (and rerun pre-commit)
138143
* if you explicitly run `pre-commit`, make sure to `git add` all changed files (just like before a commit)
139144

145+
<!-- --8<-- [end:precommit] -->
146+
140147
## Supported File Formats
141148

142149
Here is an overview of all the currently supported files and formats.
143150

144151
| Input Formats | Status | | Target Formats | Status |
145152
| -------------- | ------ |-| ----------------------------- | ------ |
146-
| (.)somesy.toml | ✓ | | pyproject.toml _(poetry)_ | ✓ |
147-
| pyproject.toml | ✓(1.) | | pyproject.toml _(setuptools)_ | ✓(2.) |
148-
| package.json | ✓ | | package.json | ✓ |
149-
| | | | mkdocs.yml | TBD |
153+
| (.)somesy.toml | ✓ | | pyproject.toml _(poetry)_ | ✓ |
154+
| pyproject.toml | ✓(1.) | | pyproject.toml _(setuptools)_ | ✓(2.) |
155+
| package.json | ✓ | | package.json | ✓(3.) |
150156
| | | | CITATION.cff | ✓ |
151-
| | | | codemeta.json | ✓(3.) |
157+
| | | | codemeta.json | ✓(4.) |
152158

153159
**Notes:**
154160

155161
1. information must be placed inside a `tool.somesy` section (as explained above)
156162
2. note that `somesy` does not support setuptools *dynamic fields*
157-
3. unlike other targets, `somesy` will *re-create* the `codemeta.json` (i.e. you should not edit it by hand!)
163+
3. `package.json` only supports one author, so `somesy` will pick the *first* listed author
164+
4. unlike other targets, `somesy` will *re-create* the `codemeta.json` (i.e. do not edit it by hand!)
158165

159166
<!-- --8<-- [end:quickstart] -->
160167

‎docs/manual.md‎

Lines changed: 128 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ metadata fields and can synchronize this information into different **target
1616
files**.
1717

1818
!!! info
19+
1920
The somesy schemas are designed to allow expressing metadata in the most
2021
useful and rich form, i.e. the best form that some of the target formats
2122
supports.
@@ -42,6 +43,7 @@ contribution of a person and acknowledge contributors that are neither full
4243
authors or maintainers.
4344

4445
!!! note
46+
4547
Currently, provided information about contributors that are neither authors
4648
nor maintainers, and all the detailed information on the contributions is
4749
not used.
@@ -110,28 +112,31 @@ The following tables sketch how fields are mapped to corresponding other fields
110112
some of the currently supported formats.
111113

112114
=== "Person Metadata"
113-
| Field Name | Poetry Config | SetupTools Config | CITATION.cff | Requirement |
114-
| ---------------- | ------------- | ----------------- | --------------- | ----------- |
115-
| given-names | name+email | name | given-names | required |
116-
| family-names | name+email | name | family-names | required |
117-
| email | name+email | email | email | required |
118-
| orcid | - | - | orcid | optional |
119-
| *(many others)* | - | - | *(same)* | optional |
115+
116+
| Field Name | Poetry Config | SetupTools Config | CITATION.cff | package.json | Requirement |
117+
| ---------------- | ------------- | ----------------- | --------------- | ------------ | ----------- |
118+
| given-names | name+email | name | given-names | name | required |
119+
| family-names | name+email | name | family-names | name | required |
120+
| email | name+email | email | email | email | required |
121+
| orcid | - | - | orcid | url | optional |
122+
| *(many others)* | - | - | *(same)* | - | optional |
120123

121124
=== "Project Metadata"
122-
| Field Name | Poetry Config | SetupTools Config | CITATION.cff | Requirement |
123-
| ----------------- | ------------- | ----------------- | --------------- | ----------- |
124-
| name | name | name | title | required |
125-
| description | description | description | abstract | required |
126-
| license | license | license | license | required |
127-
| version | version | version | version | optional |
128-
| | | | | |
129-
| *author=true* | authors | authors | authors | required |
130-
| *maintainer=true* | maintainers | maintainers | contact | optional |
131-
| | | | | |
132-
| keywords | keywords | keywords | keywords | optional |
133-
| repository | repository | urls.repository | repository_code | optional |
134-
| homepage | homepage | urls.homepage | url | optional |
125+
126+
| Field Name | Poetry Config | SetupTools Config | CITATION.cff | package.json | Requirement |
127+
| ----------------- | ------------- | ----------------- | --------------- | ------------ | ----------- |
128+
| name | name | name | title | name | required |
129+
| description | description | description | abstract | description | required |
130+
| license | license | license | license | license | required |
131+
| version | version | version | version | version | optional |
132+
| | | | | | |
133+
| *author=true* | authors | authors | authors | author | required |
134+
| *maintainer=true* | maintainers | maintainers | contact | maintainers | optional |
135+
| *people* | - | - | - | contributors | optional |
136+
| | | | | | |
137+
| keywords | keywords | keywords | keywords | keywords | optional |
138+
| repository | repository | urls.repository | repository_code | repository | optional |
139+
| homepage | homepage | urls.homepage | url | homepage | optional |
135140

136141
Note that the mapping is often not 1-to-1. For example, CITATION.cff allows rich
137142
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
158163
* `.somesy.toml`
159164
* `somesy.toml`
160165
* `pyproject.toml` (in `tool.somesy` section)
166+
* `package.json` (in `somesy` section)
161167

162168
which is located in the current working directory. If you want to provide
163169
the somesy input file from a different location, you can pass it with the `-i` option.
164170

171+
### Somesy Input File
172+
173+
Here is an example how project metadata and `somesy` can be configured using
174+
one of the supported input formats:
175+
176+
=== "somesy.toml"
177+
178+
--8<-- "README.md:somesytoml"
179+
180+
=== "pyproject.toml"
181+
182+
```toml
183+
[tool.poetry]
184+
name = "my-amazing-project"
185+
version = "0.1.0"
186+
...
187+
188+
[tool.somesy.project]
189+
name = "my-amazing-project"
190+
version = "0.1.0"
191+
description = "Brief description of my amazing software."
192+
193+
keywords = ["some", "descriptive", "keywords"]
194+
license = "MIT"
195+
repository = "https://github.com/username/my-amazing-project"
196+
197+
# This is you, the proud author of your project
198+
[[tool.somesy.project.people]]
199+
given-names = "Jane"
200+
family-names = "Doe"
201+
email = "j.doe@example.com"
202+
orcid = "https://orcid.org/0000-0000-0000-0001"
203+
author = true # is a full author of the project (i.e. appears in citations)
204+
maintainer = true # currently maintains the project (i.e. is a contact person)
205+
206+
# this person is a acknowledged contributor, but not author or maintainer:
207+
[[tool.somesy.project.people]]
208+
given-names = "Another"
209+
family-names = "Contributor"
210+
email = "a.contributor@example.com"
211+
orcid = "https://orcid.org/0000-0000-0000-0002"
212+
213+
[tool.somesy.config]
214+
verbose = true # show detailed information about what somesy is doing
215+
```
216+
217+
=== "package.json"
218+
219+
```json
220+
{
221+
"name": "my-amazing-project",
222+
"version": "0.1.0",
223+
...
224+
225+
"somesy": {
226+
"project": {
227+
"name": "my-amazing-project",
228+
"version": "0.1.0",
229+
"description": "Brief description of my amazing software.",
230+
"keywords": ["some", "descriptive", "keywords"],
231+
"license": "MIT",
232+
"repository": "https://github.com/username/my-amazing-project",
233+
"people": [
234+
{
235+
"given-names": "Jane",
236+
"family-names": "Doe",
237+
"email": "j.doe@example.com",
238+
"orcid": "https://orcid.org/0000-0000-0000-0001",
239+
"author": true,
240+
"maintainer": true
241+
},
242+
{
243+
"given-names": "Another",
244+
"family-names": "Contributor",
245+
"email": "a.contributor@example.com",
246+
"orcid": "https://orcid.org/0000-0000-0000-0002"
247+
}
248+
]
249+
},
250+
"config": {
251+
"verbose": true
252+
}
253+
}
254+
}
255+
```
256+
257+
All possible metadata fields and configuration options are explained further [above](#schemas-overview).
258+
259+
### pre-commit hook
260+
261+
--8<-- "README.md:precommit"
262+
165263
### Synchronization
166264

167265
Unless configured otherwise, `somesy` will create `CITATION.cff`
168266
and `codemeta.json` files if they do not exist.
169-
Other supported files (such as `pyproject.toml`) are updated if they already
170-
exist in your repository.
267+
Other supported files (such as `pyproject.toml` or `package.json`)
268+
are updated if they already exist in your repository.
171269

172270
If you do not want that somesy creates/synchronizes these files,
173271
you can disable them by CLI options or in your somesy configuration.
174272

175-
### Somesy input file
176-
177-
In the [quickstart](./quickstart.md) you can find an example somesy input file.
178-
179-
All possible metadata fields and configuration options are explained further [above](#schemas-overview).
180-
181273
## Metadata Update Logic
182274

183275
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
195287
and configuration you might have in a target file.
196288

197289
!!! info
290+
198291
For typically manually-edited files, it will even make sure that the
199292
comments stay in place! (currently works for TOML)
200293

201294
!!! tip
295+
202296
Only edit target files manually to add or update fields
203297
that `somesy` does **not** understand or care about!
204298

205299
!!! warning
300+
206301
All changes in target files you do to fields `somesy` *does* understand will be
207302
overwritten the next time you run somesy.
208303

@@ -218,6 +313,7 @@ most cases, but in certain tricky situations it might not be able to figure out
218313
the and needed changes correctly.
219314

220315
!!! danger
316+
221317
Always check the files that somesy synchronized look right
222318
before committing/pushing the changes!
223319

@@ -243,9 +339,11 @@ When somesy compares two metadata records about a person, it will proceed as fol
243339
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).
244340

245341
!!! tip
342+
246343
State ORCIDs for persons whenever possible (i.e. the person has an ORCID)!
247344

248345
!!! tip
346+
249347
If a person does not have an ORCID, suggest that they should create one!
250348

251349
Somesy will usually correctly understand cases such as:
@@ -259,6 +357,7 @@ Nevertheless, you should **check the changes somesy does** before committing the
259357
especially **after you significantly modified your project metadata**.
260358

261359
!!! warning
360+
262361
Note that changing the ORCID will not be recognized,
263362
because ORCIDs are assumed to be unique per person.
264363

@@ -281,6 +380,7 @@ target is enabled, `somesy` will generate your `codemeta.json` by:
281380
* running `cffconvert` and `codemetapy` to combine both sources into a final `codemeta.json`
282381

283382
!!! warning
383+
284384
The `codemeta.json` is overwritten and regenerated from scratch every time you `sync`,
285385
so **do not edit it** if you have the codemeta target enabled in `somesy`!
286386

‎docs/scripts/coverage_status.py‎

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
import anybadge
77
import pytest
88
from coverage import Coverage
9+
from coverage.exceptions import NoSource
910
from interrogate import badge_gen
1011
from interrogate.coverage import InterrogateCoverage
1112

@@ -30,10 +31,14 @@ def on_pre_build(config):
3031
else:
3132
log.info("Using existing coverage data.")
3233

33-
cov = Coverage()
34-
cov.load()
35-
cov_percent = int(cov.report(file=StringIO()))
36-
log.info(f"Test Coverage: {cov_percent}%, generating badge.")
34+
cov_percent = 0
35+
try:
36+
cov_percent = get_coverage_percentage()
37+
except NoSource:
38+
# Source file is either deleted or moved, so we can't generate a badge, rerun the tests
39+
log.info("Change in the source files, running pytest to collect.")
40+
pytest.main(["--cov", "--cov-report=html"])
41+
cov_percent = get_coverage_percentage()
3742

3843
badge = anybadge.Badge(
3944
"coverage",
@@ -52,3 +57,13 @@ def on_pre_build(config):
5257
doc_cov = InterrogateCoverage(paths=["src"]).get_coverage()
5358
log.info(f"Docs Coverage: {doc_cov.perc_covered}%, generating badge.")
5459
badge_gen.create("docs", doc_cov)
60+
61+
62+
def get_coverage_percentage():
63+
"""Return the coverage percentage from the .coverage file."""
64+
cov = Coverage()
65+
cov.load()
66+
cov_percent = cov.report(file=StringIO())
67+
log.info(f"Test Coverage: {cov_percent}%, generating badge.")
68+
69+
return cov_percent

0 commit comments

Comments
 (0)