Skip to content

Commit bdd6cb2

Browse files
mustafasoylumustafasoylu
authored
Merge pull request #74 from Materials-Data-Science-and-Informatics/feature/add-mkdocs-support
add mkdocs support
2 parents 6cf00b4 + c052aec commit bdd6cb2

15 files changed

Lines changed: 369 additions & 103 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Please consult the changelog to inform yourself about breaking changes and secur
1010
* added support for Julia `Project.toml` file
1111
* added support for Fortran `fpm.toml` file
1212
* added support for Java `pom.xml` file
13+
* added support for MkDocs `mkdocs.yml` file
1314

1415
## [v0.3.1](https://github.com/Materials-Data-Science-and-Informatics/somesy/tree/v0.3.1) <small>(2024-01-23)</small> { id="0.3.1" }
1516

‎README.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,7 @@ If you happen to use
133133
* `Project.toml` (in Julia projects),
134134
* `fpm.toml` (in Fortran projects),
135135
* `pom.xml` (in Java projects),
136+
* `mkdocs.yml` (in projects using MkDocs),
136137

137138
then somesy would also update the respective information there.
138139

@@ -181,16 +182,18 @@ Here is an overview of all the currently supported files and formats.
181182
| Project.toml | ✓ | | Project.toml _(Julia)_ | ✓ |
182183
| fpm.toml | ✓ | | fpm.toml _(Fortran)_ | ✓(3.) |
183184
| | ✓ | | pom.toml _(Java)_ | ✓(4.) |
185+
| | | | mkdocs.yml | ✓(5.) |
184186
| | | | CITATION.cff | ✓ |
185-
| | | | codemeta.json | ✓(5.) |
187+
| | | | codemeta.json | ✓(6.) |
186188

187189
**Notes:**
188190

189191
1. note that `somesy` does not support setuptools *dynamic fields*
190192
2. `package.json` only supports one author, so `somesy` will pick the *first* listed author
191193
3. `fpm.toml` only supports one author and maintainer, so `somesy` will pick the *first* listed author and maintainer
192194
4. `pom.xml` has no concept of `maintainers`, but it can have multiple licenses (somesy only supports one main project license)
193-
5. unlike other targets, `somesy` will *re-create* the `codemeta.json` (i.e. do not edit it by hand!)
195+
5. `mkdocs.yml` is a bit special, as it is not a project file, but a documentation file. `somesy` will only update it if it exists and is enabled in the configuration
196+
6. unlike other targets, `somesy` will *re-create* the `codemeta.json` (i.e. do not edit it by hand!)
194197

195198
<!-- --8<-- [end:quickstart] -->
196199

‎docs/manual.md‎

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -117,33 +117,33 @@ some of the currently supported formats. Bold field names are mandatory, the oth
117117

118118
=== "Person Metadata"
119119

120-
| Somesy Field | Poetry Config | SetupTools Config | Java POM | Julia Config | Fortran Config | package.json | CITATION.cff | CodeMeta |
121-
| ---------------- | ------------- | ----------------- | ------------ | ------------ | -------------- | ------------ | --------------- | --------------- |
122-
| | | | | | | | | |
123-
| **given-names** | name+email | name | name | name+email | name+email | name | given-names | givenName |
124-
| **family-names** | name+email | name | name | name+email | name+email | name | family-names | familyName |
125-
| **email** | name+email | email | email | name+email | name+email | email | email | email |
126-
| orcid | - | - | url | - | - | url | orcid | id |
127-
| *(many others)* | - | - | - | - | - | - | *(same)* | *(same)* |
120+
| Somesy Field | Poetry Config | SetupTools Config | Java POM | Julia Config | Fortran Config | package.json | mkdocs.yml | CITATION.cff | CodeMeta |
121+
| ---------------- | ------------- | ----------------- | ------------ | ------------ | -------------- | ------------ | ---------- | --------------- | --------------- |
122+
| | | | | | | | | | |
123+
| **given-names** | name+email | name | name | name+email | name+email | name | name+email | given-names | givenName |
124+
| **family-names** | name+email | name | name | name+email | name+email | name | name+email | family-names | familyName |
125+
| **email** | name+email | email | email | name+email | name+email | email | name+email | email | email |
126+
| orcid | - | - | url | - | - | url | - | orcid | id |
127+
| *(many others)* | - | - | - | - | - | - | - | *(same)* | *(same)* |
128128

129129
=== "Project Metadata"
130130

131-
| Somesy Field | Poetry Config | SetupTools Config | Java POM | Julia Config | Fortran Config | package.json | CITATION.cff | CodeMeta |
132-
| ----------------- | ------------- | ------------------ | ------------------------------- | ------------ | -------------- | ------------ | --------------- | ----------------- |
133-
| | | | | | | | | |
134-
| **name** | name | name | name | name | name | name | title | name |
135-
| **description** | description | description | description | - | description | description | abstract | description |
136-
| **license** | license | license | licenses.license | - | license | license | license | license |
137-
| **version** | version | version | version | version | version | version | version | version |
138-
| | | | | | | | | |
139-
| ***author=true*** | authors | authors | developers | authors | author | author | authors | author |
140-
| *maintainer=true* | maintainers | maintainers | - | - | maintainer | maintainers | contact | maintainer |
141-
| *people* | - | - | - | - | - | contributors | - | contributor |
142-
| | | | | | | | | |
143-
| keywords | keywords | keywords | - | - | keywords | keywords | keywords | keywords |
144-
| homepage | homepage | urls.homepage | urls | - | homepage | homepage | url | url |
145-
| repository | repository | urls.repository | scm.url | - | - | repository | repository_code | codeRepository |
146-
| documentation | documentation | urls.documentation | distributionManagement.site.url | - | - | - | - | buildInstructions |
131+
| Somesy Field | Poetry Config | SetupTools Config | Java POM | Julia Config | Fortran Config | package.json | mkdocs.yml | CITATION.cff | CodeMeta |
132+
| ----------------- | ------------- | ------------------ | ------------------------------- | ------------ | -------------- | ------------ | ---------------- | --------------- | ----------------- |
133+
| | | | | | | | | | |
134+
| **name** | name | name | name | name | name | name | site_name | title | name |
135+
| **description** | description | description | description | - | description | description | site_description | abstract | description |
136+
| **license** | license | license | licenses.license | - | license | license | - | license | license |
137+
| **version** | version | version | version | version | version | version | - | version | version |
138+
| | | | | | | | | | |
139+
| ***author=true*** | authors | authors | developers | authors | author | author | site_author | authors | author |
140+
| *maintainer=true* | maintainers | maintainers | - | - | maintainer | maintainers | - | contact | maintainer |
141+
| *people* | - | - | - | - | - | contributors | - | - | contributor |
142+
| | | | | | | | | | |
143+
| keywords | keywords | keywords | - | - | keywords | keywords | - | keywords | keywords |
144+
| homepage | homepage | urls.homepage | urls | - | homepage | homepage | site_url | url | url |
145+
| repository | repository | urls.repository | scm.url | - | - | repository | repo_url | repository_code | codeRepository |
146+
| documentation | documentation | urls.documentation | distributionManagement.site.url | - | - | - | - | - | buildInstructions |
147147

148148
Note that the mapping is often not 1-to-1. For example, CITATION.cff allows rich
149149
specification of author contact information and complex names. In contrast,

‎mkdocs.yml‎

Lines changed: 77 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,35 @@
11
# basic configuration:
22
site_name: "somesy"
3-
site_description: "Somesy is a CLI tool to avoid messy software project metadata by keeping it in sync."
3+
site_description: "A CLI tool for synchronizing software project metadata."
44
site_url: "https://materials-data-science-and-informatics.github.io/somesy"
55
repo_url: "https://github.com/Materials-Data-Science-and-Informatics/somesy"
66
edit_uri: "blob/main/docs/"
77
repo_name: "Materials-Data-Science-and-Informatics/somesy"
88

99
# navigation structure (TOC + respective markdown files):
1010
nav:
11-
- Home:
12-
- Overview: index.md
13-
- Changelog: changelog.md
14-
- Credits: credits.md
15-
- License: license.md
16-
- Usage:
17-
- Quickstart: quickstart.md
18-
- User Manual: manual.md
19-
- API: reference/ # auto-generated (from Python docstrings)
20-
- Development:
21-
- How To Contribute: contributing.md
22-
- Developer Guide: dev_guide.md
23-
- Code of Conduct: code_of_conduct.md
24-
- Coverage Report: coverage.md # cov report (pytest --cov --cov-report html)
11+
- Home:
12+
- Overview: index.md
13+
- Changelog: changelog.md
14+
- Credits: credits.md
15+
- License: license.md
16+
- Usage:
17+
- Quickstart: quickstart.md
18+
- User Manual: manual.md
19+
- API: reference/ # auto-generated (from Python docstrings)
20+
- Development:
21+
- How To Contribute: contributing.md
22+
- Developer Guide: dev_guide.md
23+
- Code of Conduct: code_of_conduct.md
24+
- Coverage Report: coverage.md # cov report (pytest --cov --cov-report html)
2525

2626
extra:
2727
# social links in footer:
2828
social:
29-
- icon: 'fontawesome/brands/github'
30-
link: 'https://github.com/Materials-Data-Science-and-Informatics'
31-
- icon: 'fontawesome/solid/globe'
32-
link: 'https://github.com/Materials-Data-Science-and-Informatics'
29+
- icon: 'fontawesome/brands/github'
30+
link: 'https://github.com/Materials-Data-Science-and-Informatics'
31+
- icon: 'fontawesome/solid/globe'
32+
link: 'https://github.com/Materials-Data-Science-and-Informatics'
3333

3434
# versioned docs: https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/
3535
version:
@@ -63,93 +63,94 @@ theme:
6363

6464
# light/dark mode toggle: https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/
6565
palette:
66-
- media: "(prefers-color-scheme: light)"
67-
scheme: default
68-
toggle:
69-
icon: material/brightness-7
70-
name: Switch to dark mode
71-
- media: "(prefers-color-scheme: dark)"
72-
scheme: slate
73-
toggle:
74-
icon: material/brightness-4
75-
name: Switch to light mode
66+
- media: "(prefers-color-scheme: light)"
67+
scheme: default
68+
toggle:
69+
icon: material/brightness-7
70+
name: Switch to dark mode
71+
- media: "(prefers-color-scheme: dark)"
72+
scheme: slate
73+
toggle:
74+
icon: material/brightness-4
75+
name: Switch to light mode
7676
logo: "https://github.com/Materials-Data-Science-and-Informatics/Logos/raw/main/Somesy/Somesy_Logo.png"
7777
favicon: "https://github.com/Materials-Data-Science-and-Informatics/Logos/raw/main/Somesy/Somesy_Logo.png"
7878

7979
extra_css:
8080
# list of extra CSS files to override and configure defaults:
81-
- css/style.css
81+
- css/style.css
8282

8383
markdown_extensions:
8484
# Enable permalink to sections:
85-
- toc:
86-
permalink: true
85+
- toc:
86+
permalink: true
8787
# Setting HTML/CSS attributes: https://python-markdown.github.io/extensions/attr_list/
88-
- attr_list
88+
- attr_list
8989
# Definitions: https://python-markdown.github.io/extensions/definition_lists/
90-
- def_list
90+
- def_list
9191
# Footnotes: https://squidfunk.github.io/mkdocs-material/reference/footnotes/
92-
- footnotes
92+
- footnotes
9393
# Various boxes: https://squidfunk.github.io/mkdocs-material/reference/admonitions/
94-
- admonition
95-
- pymdownx.details
96-
- pymdownx.superfences
94+
- admonition
95+
- pymdownx.details
96+
- pymdownx.superfences
9797
# smart links: https://facelessuser.github.io/pymdown-extensions/extensions/magiclink/
98-
- pymdownx.magiclink:
99-
repo_url_shorthand: true
98+
- pymdownx.magiclink:
99+
repo_url_shorthand: true
100100
# Superscript: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
101-
- pymdownx.caret
101+
- pymdownx.caret
102102
# Strikethrough markup: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
103-
- pymdownx.tilde
103+
- pymdownx.tilde
104104
# Auto-Unicode for common symbols: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
105-
- pymdownx.smartsymbols
105+
- pymdownx.smartsymbols
106106
# Github-style task list: https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#tasklist
107-
- pymdownx.tasklist:
108-
custom_checkbox: true
107+
- pymdownx.tasklist:
108+
custom_checkbox: true
109109
# Tabbed boxes: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
110-
- pymdownx.tabbed:
111-
alternate_style: true
110+
- pymdownx.tabbed:
111+
alternate_style: true
112112
# Inlining markdown: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
113-
- pymdownx.snippets:
114-
check_paths: true
113+
- pymdownx.snippets:
114+
check_paths: true
115115
# Icons and Emoji: https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/
116-
- pymdownx.emoji:
117-
emoji_index: !!python/name:material.extensions.emoji.twemoji
118-
emoji_generator: !!python/name:material.extensions.emoji.to_svg
116+
- pymdownx.emoji:
117+
emoji_index: !!python/name:material.extensions.emoji.twemoji
118+
emoji_generator: !!python/name:material.extensions.emoji.to_svg
119119

120120
plugins:
121121
# default search box (must be listed if plugins are added)
122-
- search
122+
- search
123123
# embed coverage report: https://pawamoy.github.io/mkdocs-coverage/
124-
- coverage
124+
- coverage
125125
# execute code (e.g. generate diagrams): https://pawamoy.github.io/markdown-exec/
126-
- markdown-exec
126+
- markdown-exec
127127
# automatic API docs: https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages
128-
- gen-files:
129-
scripts:
130-
- docs/scripts/gen_ref_pages.py
131-
- literate-nav:
132-
nav_file: SUMMARY.md
133-
- section-index
134-
- mkdocstrings:
135-
handlers:
136-
python:
137-
paths: [src]
138-
options:
139-
members_order: source
140-
separate_signature: true
141-
show_signature_annotations: true
128+
- gen-files:
129+
scripts:
130+
- docs/scripts/gen_ref_pages.py
131+
- literate-nav:
132+
nav_file: SUMMARY.md
133+
- section-index
134+
- mkdocstrings:
135+
handlers:
136+
python:
137+
paths: [src]
138+
options:
139+
members_order: source
140+
separate_signature: true
141+
show_signature_annotations: true
142142
# https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/#built-in-offline-plugin
143143
# To allow building for offline usage, e.g. with: OFFLINE=true mkdocs build
144-
- offline:
145-
enabled: !ENV [OFFLINE, false]
144+
- offline:
145+
enabled: !ENV [OFFLINE, false]
146146
# to make multi-version docs work right
147-
- mike
148-
- exclude:
149-
glob:
150-
- "_*.md" # for internal purposes
147+
- mike
148+
- exclude:
149+
glob:
150+
- "_*.md" # for internal purposes
151151

152152
hooks:
153-
- docs/scripts/coverage_status.py
153+
- docs/scripts/coverage_status.py
154154

155155
strict: true
156+
site_author: Mustafa Soylu <m.soylu@fz-juelich.de>

‎src/somesy/cli/init.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,12 @@ def config():
7878
if pom_xml_file := typer.prompt("pom.xml file path", default="pom.xml"):
7979
options["pom_xml_file"] = pom_xml_file
8080

81+
options["no_sync_mkdocs"] = not typer.confirm(
82+
"Do you want to sync to a mkdocs.yml file?", default=True
83+
)
84+
if mkdocs_file := typer.prompt("mkdocs.yml file path", default="mkdocs.yml"):
85+
options["mkdocs_file"] = mkdocs_file
86+
8187
# ----
8288

8389
options["show_info"] = typer.confirm(

‎src/somesy/cli/sync.py‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,19 @@ def sync(
9494
help="Custom pom.xml (Java Maven) file path (default: pom.xml)",
9595
**existing_file_arg_config,
9696
),
97+
no_sync_mkdocs: bool = typer.Option(
98+
None,
99+
"--no-sync-mkdocs",
100+
"-D",
101+
help="Do not sync mkdocs.yml file (default: False)",
102+
),
103+
mkdocs_file: Path = typer.Option(
104+
None,
105+
"--mkdocs-file",
106+
"-d",
107+
help="Custom mkdocs.yml file path (default: mkdocs.yml)",
108+
**existing_file_arg_config,
109+
),
97110
no_sync_cff: bool = typer.Option(
98111
None,
99112
"--no-sync-cff",
@@ -138,6 +151,8 @@ def sync(
138151
fortran_file=fortran_file,
139152
no_sync_pom_xml=no_sync_pom_xml,
140153
pom_xml_file=pom_xml_file,
154+
no_sync_mkdocs=no_sync_mkdocs,
155+
mkdocs_file=mkdocs_file,
141156
)
142157
run_sync(somesy_input)
143158

@@ -167,6 +182,10 @@ def run_sync(somesy_input: SomesyInput):
167182
logger.info(
168183
f" - [italic]pom.xml[/italic]:\t[grey]{conf.pom_xml_file}[/grey]\n"
169184
)
185+
if not conf.no_sync_mkdocs:
186+
logger.info(
187+
f" - [italic]mkdocs.yml[/italic]:\t[grey]{conf.mkdocs_file}[/grey]"
188+
)
170189

171190
if not conf.no_sync_cff:
172191
logger.info(f" - [italic]CITATION.cff[/italic]:\t[grey]{conf.cff_file}[/grey]")

0 commit comments

Comments
 (0)