Merge branch 'main' into feature/add-rust-support

Author: mustafasoylu

CHANGELOG.md

@@ -10,6 +10,7 @@ Please consult the changelog to inform yourself about breaking changes and secur
 * added support for Julia `Project.toml` file
 * added support for Fortran `fpm.toml` file
 * added support for Java `pom.xml` file
+* added support for MkDocs `mkdocs.yml` file
 
 ## [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" }
 

README.md

@@ -133,6 +133,7 @@ If you happen to use
 * `Project.toml` (in Julia projects),
 * `fpm.toml` (in Fortran projects),
 * `pom.xml` (in Java projects),
+* `mkdocs.yml` (in projects using MkDocs),
 
 then somesy would also update the respective information there.
 
@@ -181,16 +182,18 @@ Here is an overview of all the currently supported files and formats.
 | Project.toml   | ✓      | | Project.toml _(Julia)_        | ✓      |
 | fpm.toml       | ✓      | | fpm.toml _(Fortran)_          | ✓(3.)  |
 |                | ✓      | | pom.toml _(Java)_             | ✓(4.)  |
+|                |        | | mkdocs.yml                    | ✓(5.)  |
 |                |        | | CITATION.cff                  | ✓      |
-|                |        | | codemeta.json                 | ✓(5.)  |
+|                |        | | codemeta.json                 | ✓(6.)  |
 
 **Notes:**
 
 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. `fpm.toml` only supports one author and maintainer, so `somesy` will pick the *first* listed author and maintainer
 4. `pom.xml` has no concept of `maintainers`, but it can have multiple licenses (somesy only supports one main project license)
-5. unlike other targets, `somesy` will *re-create* the `codemeta.json` (i.e. do not edit it by hand!)
+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
+6. unlike other targets, `somesy` will *re-create* the `codemeta.json` (i.e. do not edit it by hand!)
 
 <!-- --8<-- [end:quickstart] -->
 

docs/manual.md

@@ -117,33 +117,33 @@ some of the currently supported formats. Bold field names are mandatory, the oth
 
 === "Person Metadata"
 
-    | Somesy Field     | Poetry Config | SetupTools Config | Java POM     | Julia Config | Fortran Config | package.json | CITATION.cff    | CodeMeta        |
-    | ---------------- | ------------- | ----------------- | ------------ | ------------ | -------------- | ------------ | --------------- | --------------- |
-    |                  |               |                   |              |              |                |              |                 |                 |
-    | **given-names**  | name+email    | name              | name         | name+email   | name+email     | name         | given-names     | givenName       |
-    | **family-names** | name+email    | name              | name         | name+email   | name+email     | name         | family-names    | familyName      |
-    | **email**        | name+email    | email             | email        | name+email   | name+email     | email        | email           | email           |
-    | orcid            | -             | -                 | url          | -            | -              | url          | orcid           | id              |
-    | *(many others)*  | -             | -                 | -            | -            | -              | -            | *(same)*        | *(same)*        |
+    | Somesy Field     | Poetry Config | SetupTools Config | Java POM     | Julia Config | Fortran Config | package.json | mkdocs.yml | CITATION.cff    | CodeMeta        |
+    | ---------------- | ------------- | ----------------- | ------------ | ------------ | -------------- | ------------ | ---------- | --------------- | --------------- |
+    |                  |               |                   |              |              |                |              |            |                 |                 |
+    | **given-names**  | name+email    | name              | name         | name+email   | name+email     | name         | name+email | given-names     | givenName       |
+    | **family-names** | name+email    | name              | name         | name+email   | name+email     | name         | name+email | family-names    | familyName      |
+    | **email**        | name+email    | email             | email        | name+email   | name+email     | email        | name+email | email           | email           |
+    | orcid            | -             | -                 | url          | -            | -              | url          | -          | orcid           | id              |
+    | *(many others)*  | -             | -                 | -            | -            | -              | -            | -          | *(same)*        | *(same)*        |
 
 === "Project Metadata"
 
-    | Somesy Field      | Poetry Config | SetupTools Config  | Java POM                        | Julia Config | Fortran Config | package.json | CITATION.cff    | CodeMeta          |
-    | ----------------- | ------------- | ------------------ | ------------------------------- | ------------ | -------------- | ------------ | --------------- | ----------------- |
-    |                   |               |                    |                                 |              |                |              |                 |                   |
-    | **name**          | name          | name               | name                            | name         | name           | name         | title           | name              |
-    | **description**   | description   | description        | description                     | -            | description    | description  | abstract        | description       |
-    | **license**       | license       | license            | licenses.license                | -            | license        | license      | license         | license           |
-    | **version**       | version       | version            | version                         | version      | version        | version      | version         | version           |
-    |                   |               |                    |                                 |              |                |              |                 |                   |
-    | ***author=true*** | authors       | authors            | developers                      | authors      | author         | author       | authors         | author            |
-    | *maintainer=true* | maintainers   | maintainers        | -                               | -            | maintainer     | maintainers  | contact         | maintainer        |
-    | *people*          | -             | -                  | -                               | -            | -              | contributors | -               | contributor       |
-    |                   |               |                    |                                 |              |                |              |                 |                   |
-    | keywords          | keywords      | keywords           | -                               | -            | keywords       | keywords     | keywords        | keywords          |
-    | homepage          | homepage      | urls.homepage      | urls                            | -            | homepage       | homepage     | url             | url               |
-    | repository        | repository    | urls.repository    | scm.url                         | -            | -              | repository   | repository_code | codeRepository    |
-    | documentation     | documentation | urls.documentation | distributionManagement.site.url | -            | -              | -            | -               | buildInstructions |
+    | Somesy Field      | Poetry Config | SetupTools Config  | Java POM                        | Julia Config | Fortran Config | package.json | mkdocs.yml       | CITATION.cff    | CodeMeta          |
+    | ----------------- | ------------- | ------------------ | ------------------------------- | ------------ | -------------- | ------------ | ---------------- | --------------- | ----------------- |
+    |                   |               |                    |                                 |              |                |              |                  |                 |                   |
+    | **name**          | name          | name               | name                            | name         | name           | name         | site_name        | title           | name              |
+    | **description**   | description   | description        | description                     | -            | description    | description  | site_description | abstract        | description       |
+    | **license**       | license       | license            | licenses.license                | -            | license        | license      | -                | license         | license           |
+    | **version**       | version       | version            | version                         | version      | version        | version      | -                | version         | version           |
+    |                   |               |                    |                                 |              |                |              |                  |                 |                   |
+    | ***author=true*** | authors       | authors            | developers                      | authors      | author         | author       | site_author      | authors         | author            |
+    | *maintainer=true* | maintainers   | maintainers        | -                               | -            | maintainer     | maintainers  | -                | contact         | maintainer        |
+    | *people*          | -             | -                  | -                               | -            | -              | contributors | -                | -               | contributor       |
+    |                   |               |                    |                                 |              |                |              |                  |                 |                   |
+    | keywords          | keywords      | keywords           | -                               | -            | keywords       | keywords     | -                | keywords        | keywords          |
+    | homepage          | homepage      | urls.homepage      | urls                            | -            | homepage       | homepage     | site_url         | url             | url               |
+    | repository        | repository    | urls.repository    | scm.url                         | -            | -              | repository   | repo_url         | repository_code | codeRepository    |
+    | documentation     | documentation | urls.documentation | distributionManagement.site.url | -            | -              | -            | -                | -               | buildInstructions |
 
 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,

mkdocs.yml

@@ -1,35 +1,35 @@
 # basic configuration:
 site_name: "somesy"
-site_description: "Somesy is a CLI tool to avoid messy software project metadata by keeping it in sync."
+site_description: "A CLI tool for synchronizing software project metadata."
 site_url: "https://materials-data-science-and-informatics.github.io/somesy"
 repo_url: "https://github.com/Materials-Data-Science-and-Informatics/somesy"
 edit_uri: "blob/main/docs/"
 repo_name: "Materials-Data-Science-and-Informatics/somesy"
 
 # navigation structure (TOC + respective markdown files):
 nav:
-  - Home:
-    - Overview: index.md
-    - Changelog: changelog.md
-    - Credits: credits.md
-    - License: license.md
-  - Usage:
-    - Quickstart: quickstart.md
-    - User Manual: manual.md
-    - API: reference/              # auto-generated (from Python docstrings)
-  - Development:
-    - How To Contribute: contributing.md
-    - Developer Guide: dev_guide.md
-    - Code of Conduct: code_of_conduct.md
-    - Coverage Report: coverage.md # cov report (pytest --cov --cov-report html)
+- Home:
+  - Overview: index.md
+  - Changelog: changelog.md
+  - Credits: credits.md
+  - License: license.md
+- Usage:
+  - Quickstart: quickstart.md
+  - User Manual: manual.md
+  - API: reference/                # auto-generated (from Python docstrings)
+- Development:
+  - How To Contribute: contributing.md
+  - Developer Guide: dev_guide.md
+  - Code of Conduct: code_of_conduct.md
+  - Coverage Report: coverage.md   # cov report (pytest --cov --cov-report html)
 
 extra:
   # social links in footer:
   social:
-    - icon: 'fontawesome/brands/github'
-      link: 'https://github.com/Materials-Data-Science-and-Informatics'
-    - icon: 'fontawesome/solid/globe'
-      link: 'https://github.com/Materials-Data-Science-and-Informatics'
+  - icon: 'fontawesome/brands/github'
+    link: 'https://github.com/Materials-Data-Science-and-Informatics'
+  - icon: 'fontawesome/solid/globe'
+    link: 'https://github.com/Materials-Data-Science-and-Informatics'
 
   # versioned docs: https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/
   version:
@@ -63,93 +63,94 @@ theme:
 
   # light/dark mode toggle: https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/
   palette:
-    - media: "(prefers-color-scheme: light)"
-      scheme: default
-      toggle:
-        icon: material/brightness-7
-        name: Switch to dark mode
-    - media: "(prefers-color-scheme: dark)"
-      scheme: slate
-      toggle:
-        icon: material/brightness-4
-        name: Switch to light mode
+  - media: "(prefers-color-scheme: light)"
+    scheme: default
+    toggle:
+      icon: material/brightness-7
+      name: Switch to dark mode
+  - media: "(prefers-color-scheme: dark)"
+    scheme: slate
+    toggle:
+      icon: material/brightness-4
+      name: Switch to light mode
   logo: "https://github.com/Materials-Data-Science-and-Informatics/Logos/raw/main/Somesy/Somesy_Logo.png"
   favicon: "https://github.com/Materials-Data-Science-and-Informatics/Logos/raw/main/Somesy/Somesy_Logo.png"
 
 extra_css:
   # list of extra CSS files to override and configure defaults:
-  - css/style.css
+- css/style.css
 
 markdown_extensions:
   # Enable permalink to sections:
-  - toc:
-      permalink: true
+- toc:
+    permalink: true
   # Setting HTML/CSS attributes: https://python-markdown.github.io/extensions/attr_list/
-  - attr_list
+- attr_list
   # Definitions: https://python-markdown.github.io/extensions/definition_lists/
-  - def_list
+- def_list
   # Footnotes: https://squidfunk.github.io/mkdocs-material/reference/footnotes/
-  - footnotes
+- footnotes
   # Various boxes: https://squidfunk.github.io/mkdocs-material/reference/admonitions/
-  - admonition
-  - pymdownx.details
-  - pymdownx.superfences
+- admonition
+- pymdownx.details
+- pymdownx.superfences
   # smart links: https://facelessuser.github.io/pymdown-extensions/extensions/magiclink/
-  - pymdownx.magiclink:
-      repo_url_shorthand: true
+- pymdownx.magiclink:
+    repo_url_shorthand: true
   # Superscript: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
-  - pymdownx.caret
+- pymdownx.caret
   # Strikethrough markup: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
-  - pymdownx.tilde
+- pymdownx.tilde
   # Auto-Unicode for common symbols: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
-  - pymdownx.smartsymbols
+- pymdownx.smartsymbols
   # Github-style task list: https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#tasklist
-  - pymdownx.tasklist:
-      custom_checkbox: true
+- pymdownx.tasklist:
+    custom_checkbox: true
   # Tabbed boxes: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
-  - pymdownx.tabbed:
-      alternate_style: true
+- pymdownx.tabbed:
+    alternate_style: true
   # Inlining markdown: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
-  - pymdownx.snippets:
-      check_paths: true
+- pymdownx.snippets:
+    check_paths: true
   # Icons and Emoji: https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/
-  - pymdownx.emoji:
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+- pymdownx.emoji:
+    emoji_index: !!python/name:material.extensions.emoji.twemoji
+    emoji_generator: !!python/name:material.extensions.emoji.to_svg
 
 plugins:
   # default search box (must be listed if plugins are added)
-  - search
+- search
   # embed coverage report: https://pawamoy.github.io/mkdocs-coverage/
-  - coverage
+- coverage
   # execute code (e.g. generate diagrams): https://pawamoy.github.io/markdown-exec/
-  - markdown-exec
+- markdown-exec
   # automatic API docs: https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages
-  - gen-files:
-      scripts:
-      - docs/scripts/gen_ref_pages.py
-  - literate-nav:
-      nav_file: SUMMARY.md
-  - section-index
-  - mkdocstrings:
-      handlers:
-        python:
-          paths: [src]
-          options:
-            members_order: source
-            separate_signature: true
-            show_signature_annotations: true
+- gen-files:
+    scripts:
+    - docs/scripts/gen_ref_pages.py
+- literate-nav:
+    nav_file: SUMMARY.md
+- section-index
+- mkdocstrings:
+    handlers:
+      python:
+        paths: [src]
+        options:
+          members_order: source
+          separate_signature: true
+          show_signature_annotations: true
   # https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/#built-in-offline-plugin
   # To allow building for offline usage, e.g. with: OFFLINE=true mkdocs build
-  - offline:
-      enabled: !ENV [OFFLINE, false]
+- offline:
+    enabled: !ENV [OFFLINE, false]
   # to make multi-version docs work right
-  - mike
-  - exclude:
-      glob:
-        - "_*.md"  # for internal purposes
+- mike
+- exclude:
+    glob:
+    - "_*.md"      # for internal purposes
 
 hooks:
-  - docs/scripts/coverage_status.py
+- docs/scripts/coverage_status.py
 
 strict: true
+site_author: Mustafa Soylu <m.soylu@fz-juelich.de>

src/somesy/cli/init.py

@@ -78,6 +78,12 @@ def config():
     if pom_xml_file := typer.prompt("pom.xml file path", default="pom.xml"):
         options["pom_xml_file"] = pom_xml_file
 
+    options["no_sync_mkdocs"] = not typer.confirm(
+        "Do you want to sync to a mkdocs.yml file?", default=True
+    )
+    if mkdocs_file := typer.prompt("mkdocs.yml file path", default="mkdocs.yml"):
+        options["mkdocs_file"] = mkdocs_file
+
     # ----
 
     options["show_info"] = typer.confirm(

src/somesy/cli/sync.py

@@ -94,6 +94,19 @@ def sync(
         help="Custom pom.xml (Java Maven) file path (default: pom.xml)",
         **existing_file_arg_config,
     ),
+    no_sync_mkdocs: bool = typer.Option(
+        None,
+        "--no-sync-mkdocs",
+        "-D",
+        help="Do not sync mkdocs.yml file (default: False)",
+    ),
+    mkdocs_file: Path = typer.Option(
+        None,
+        "--mkdocs-file",
+        "-d",
+        help="Custom mkdocs.yml file path (default: mkdocs.yml)",
+        **existing_file_arg_config,
+    ),
     no_sync_cff: bool = typer.Option(
         None,
         "--no-sync-cff",
@@ -138,6 +151,8 @@ def sync(
         fortran_file=fortran_file,
         no_sync_pom_xml=no_sync_pom_xml,
         pom_xml_file=pom_xml_file,
+        no_sync_mkdocs=no_sync_mkdocs,
+        mkdocs_file=mkdocs_file,
     )
     run_sync(somesy_input)
 
@@ -167,6 +182,10 @@ def run_sync(somesy_input: SomesyInput):
         logger.info(
             f"  - [italic]pom.xml[/italic]:\t[grey]{conf.pom_xml_file}[/grey]\n"
         )
+    if not conf.no_sync_mkdocs:
+        logger.info(
+            f"  - [italic]mkdocs.yml[/italic]:\t[grey]{conf.mkdocs_file}[/grey]"
+        )
 
     if not conf.no_sync_cff:
         logger.info(f"  - [italic]CITATION.cff[/italic]:\t[grey]{conf.cff_file}[/grey]")