Skip to content

Commit

Permalink
Merge pull request #74 from Materials-Data-Science-and-Informatics/fe…
Browse files Browse the repository at this point in the history 
…ature/add-mkdocs-support

add mkdocs support
  • Loading branch information
@mustafasoylu
mustafasoylu authored Feb 26, 2024
2 parents 6cf00b4 + c052aec commit bdd6cb2
Show file tree
Hide file tree
Showing 15 changed files with 369 additions and 103 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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" }

Expand Down
7 changes: 5 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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] -->

Expand Down
48 changes: 24 additions & 24 deletions docs/manual.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
153 changes: 77 additions & 76 deletions mkdocs.yml
View file
Original file line number Diff line number Diff line change
@@ -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:
Expand Down Expand Up @@ -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>
6 changes: 6 additions & 0 deletions src/somesy/cli/init.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
19 changes: 19 additions & 0 deletions src/somesy/cli/sync.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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]")
Expand Down
Loading

0 comments on commit bdd6cb2

Please sign in to comment.