From 201726746ed49eb4242878bd9d56849ee212d954 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81lvaro=20Mond=C3=A9jar?= Date: Wed, 20 Dec 2023 13:41:19 +0100 Subject: [PATCH] Documentation enhancements (#188) --- .markdownlint-cli2.yaml | 2 +- .pre-commit-config.yaml | 12 ++++---- README.md | 28 ++++++++++------- locale/es/README.md | 22 ++++++++------ locale/es/README.md.po | 67 +++++++++++++++++++++-------------------- locale/fr/README.md | 22 ++++++++------ locale/fr/README.md.po | 67 +++++++++++++++++++++-------------------- 7 files changed, 118 insertions(+), 102 deletions(-) diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index 25677b8..9e94750 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -1,3 +1,3 @@ config: - no-duplicate-header: false + no-duplicate-heading: false no-inline-html: false diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index d905dfb..7534924 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,6 +1,6 @@ repos: - repo: https://github.com/pre-commit/mirrors-prettier - rev: v3.0.3 + rev: v4.0.0-alpha.7 hooks: - id: prettier types_or: @@ -16,7 +16,7 @@ repos: minimum_pre_commit_version: 2.9.0 exclude: ^locale - repo: https://github.com/mondeja/project-config - rev: v0.9.2 + rev: v0.9.3 hooks: - id: project-config - repo: meta @@ -33,7 +33,7 @@ repos: - id: end-of-file-fixer name: end-of-file-fixer - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.0.292 + rev: v0.1.8 hooks: - id: ruff args: @@ -63,11 +63,11 @@ repos: - id: untranslated-messages - id: remove-metadata - repo: https://github.com/adrienverge/yamllint - rev: v1.32.0 + rev: v1.33.0 hooks: - id: yamllint - repo: https://github.com/DavidAnson/markdownlint-cli2 - rev: v0.10.0 + rev: v0.11.0 hooks: - id: markdownlint-cli2 name: markdownlint-readme @@ -79,7 +79,7 @@ repos: name: editorconfig-checker alias: ec - repo: https://github.com/pre-commit/mirrors-mypy - rev: v1.6.0 + rev: v1.7.1 hooks: - id: mypy files: ^src diff --git a/README.md b/README.md index 0832982..a8c89b3 100644 --- a/README.md +++ b/README.md @@ -61,9 +61,9 @@ plugins: end: ``` -- # **opening_tag** and - **closing_tag**: The default opening and closing tags. By default are - `{%` and `%}`. +#### `opening_tag` and `closing_tag` + +Default opening and closing tags. When not specified they are `{%` and `%}`. ```yaml plugins: @@ -72,9 +72,12 @@ plugins: closing_tag: "!}" ``` -- # **exclude**: Define - global exclusion wildcard patterns. Relative paths defined here will be - relative to the _docs/_ directory. + + +#### `exclude` + +Global exclusion wildcard patterns. Relative paths defined here will be +relative to the [`docs_dir`] directory. ```yaml plugins: @@ -84,9 +87,11 @@ plugins: - api/** ``` -- # **cache**: Define a - expiration time in seconds for cached HTTP requests when including - from URLs. + + +#### `cache` + +Expiration time in seconds for cached HTTP requests when including from URLs. ```yaml plugins: @@ -113,8 +118,8 @@ Paths of included files can be either: - Local files: - Absolute paths (starting with a path separator). - Relative from the file that includes them (starting with `./` or `../`). - - Relative to the `docs_dir` directory. For instance if your `docs_dir` is - _./docs/_, then `includes/header.md` will match the file _./docs/includes/header.md_`. + - Relative to the [`docs_dir`] directory. For instance if your `docs_dir` is + _./docs/_, then `includes/header.md` will match the file _./docs/includes/header.md_. - [Bash wildcard globs] matching multiple local files. File paths to include and string arguments can be wrapped by double `"` or @@ -283,3 +288,4 @@ Includes the content of a file or a group of files. [es-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/es/README.md [fr-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/fr/README.md [Bash wildcard globs]: https://facelessuser.github.io/wcmatch/glob/#syntax +[`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir diff --git a/locale/es/README.md b/locale/es/README.md index 3e14702..95e8fc5 100644 --- a/locale/es/README.md +++ b/locale/es/README.md @@ -50,8 +50,9 @@ plugins: end: ``` -- # **opening_tag** and -**closing_tag**: Las etiquetas de apertura y cierre. Por defecto son `{%` y +#### `opening_tag` y `closing_tag` + +Etiquetas de apertura y cierre por defecto. Cuando no se especifican son `{%` y `%}`. ```yaml @@ -61,9 +62,10 @@ plugins: closing_tag: "!}" ``` -- # **exclude**: Define -patrones de comodín de exclusión globales. Las rutas relativas definidas aquí -serán relativas al directorio *docs/*. +#### `exclude` + +Patrones de comodín de exclusión globales. Las rutas relativas definidas aquí +serán relativas al directorio [`docs_dir`]. ```yaml plugins: @@ -73,8 +75,9 @@ plugins: - api/** ``` -- # **cache**: Define un tiempo -de caducidad en segundos para las solicitudes HTTP almacenadas en caché al +#### `cache` + +Tiempo de caducidad en segundos para las solicitudes HTTP almacenadas en caché al incluir desde URL. ```yaml @@ -102,8 +105,8 @@ Las rutas de los archivos a incluir pueden ser: - Archivos locales: - Rutas absolutas (comenzando con un separador de rutas). - Relativas desde el archivo que las incluye (empezando por `./` o `../`). - - Relativo al directorio `docs_dir`. Por ejemplo, si tu `docs_dir` es _./docs/_, -entonces `includes/header.md` coincidirá con el archivo + - Relativo al directorio [`docs_dir`]. Por ejemplo, si tu `docs_dir` es +_./docs/_, entonces `includes/header.md` coincidirá con el archivo *_./docs/includes/header.md_*. - [Bash wildcard globs] matching multiple local files. [Patrones glob de Bash] @@ -279,3 +282,4 @@ separar este plugin de la documentación de [es-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/es/README.md [fr-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/fr/README.md [Bash wildcard globs]: https://facelessuser.github.io/wcmatch/glob/#syntax +[`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir diff --git a/locale/es/README.md.po b/locale/es/README.md.po index c186fab..dbf304e 100644 --- a/locale/es/README.md.po +++ b/locale/es/README.md.po @@ -27,9 +27,6 @@ msgstr "" "Incluye contenido de archivos Markdown, opcionalmente usando dos " "delimitadores para filtrar el contenido a incluir." -msgid "Examples" -msgstr "Ejemplos" - msgid "Acknowledgment" msgstr "Agradecimiento" @@ -285,15 +282,6 @@ msgstr "" "El comportamiento global del plugin puede ser personalizado en la " "configuración." -msgid "" -"# **opening_tag** and " -"**closing_tag**: The default opening and closing tags. By default are `{%` " -"and `%}`." -msgstr "" -"# **opening_tag** and " -"**closing_tag**: Las etiquetas de apertura y cierre. Por defecto son `{%` y " -"`%}`." - msgid "[pypi-link]: https://pypi.org/project/mkdocs-include-markdown-plugin" msgstr "[pypi-link]: https://pypi.org/project/mkdocs-include-markdown-plugin" @@ -367,24 +355,6 @@ msgid "" msgstr "" "[Bash wildcard globs]: https://facelessuser.github.io/wcmatch/glob/#syntax" -msgid "" -"# **exclude**: " -"Define global exclusion wildcard patterns. Relative paths defined here will " -"be relative to the *docs/* directory." -msgstr "" -"# **exclude**: " -"Define patrones de comodín de exclusión globales. Las rutas relativas " -"definidas aquí serán relativas al directorio *docs/*." - -msgid "" -"# **cache**: Define a " -"expiration time in seconds for cached HTTP requests when including from " -"URLs." -msgstr "" -"# **cache**: Define un " -"tiempo de caducidad en segundos para las solicitudes HTTP almacenadas en " -"caché al incluir desde URL." - msgid "" "Relative from the file that includes them (starting with `./` or `../`)." msgstr "" @@ -399,11 +369,42 @@ msgstr "" "instalada. Puedes incluirla en la instalación del plugin añadiendo el extra " "`cache`:" +msgid "`opening_tag` and `closing_tag`" +msgstr "`opening_tag` y `closing_tag`" + +msgid "" +"Default opening and closing tags. When not specified they are `{%` and `%}`." +msgstr "" +"Etiquetas de apertura y cierre por defecto. Cuando no se especifican son " +"`{%` y `%}`." + +msgid "" +"Global exclusion wildcard patterns. Relative paths defined here will be " +"relative to the [`docs_dir`] directory." +msgstr "" +"Patrones de comodín de exclusión globales. Las rutas relativas definidas " +"aquí serán relativas al directorio [`docs_dir`]." + +msgid "" +"Expiration time in seconds for cached HTTP requests when including from " +"URLs." +msgstr "" +"Tiempo de caducidad en segundos para las solicitudes HTTP almacenadas en " +"caché al incluir desde URL." + +msgid "" +"[`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir" +msgstr "" +"[`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir" + +msgid "Examples" +msgstr "Ejemplos" + msgid "" -"Relative to the `docs_dir` directory. For instance if your `docs_dir` is " +"Relative to the [`docs_dir`] directory. For instance if your `docs_dir` is " "*./docs/*, then `includes/header.md` will match the file " -"*./docs/includes/header.md*`." +"*./docs/includes/header.md*." msgstr "" -"Relativo al directorio `docs_dir`. Por ejemplo, si tu `docs_dir` es " +"Relativo al directorio [`docs_dir`]. Por ejemplo, si tu `docs_dir` es " "_./docs/_, entonces `includes/header.md` coincidirá con el archivo " "*_./docs/includes/header.md_*." diff --git a/locale/fr/README.md b/locale/fr/README.md index 7d49565..4e90c2f 100644 --- a/locale/fr/README.md +++ b/locale/fr/README.md @@ -49,9 +49,10 @@ plugins: end: ``` -- # **opening_tag** and -**closing_tag**: Les balises d'ouverture et de fermeture par défaut. Par -défaut sont `{%` et `%}`. +#### `opening_tag` et `closing_tag` + +Balises d'ouverture et de fermeture par défaut. Lorsqu'elles ne sont pas +spécifiées, elles sont `{%` et `%}`. ```yaml plugins: @@ -60,9 +61,10 @@ plugins: closing_tag: "!}" ``` -- # **exclude**: Définissez -des modèles génériques d'exclusion globale. Les chemins de fichiers relatifs -définis ici seront relatifs au répertoire *docs/*. +#### `exclude` + +Modèles de globes d'exclusion globaux. Les chemins relatifs définis ici seront +relatifs au répertoire [`docs_dir`]. ```yaml plugins: @@ -72,8 +74,9 @@ plugins: - api/** ``` -- # **cache**: Définissez un -délai d'expiration en secondes pour les requêtes HTTP mises en cache lors de +#### `cache` + +Délai d'expiration en secondes pour les requêtes HTTP mises en cache lors de l'inclusion d'URL. ```yaml @@ -102,7 +105,7 @@ Les chemins des fichiers inclus peuvent être soit: - Fichiers locaux: - Chemins de fichier absolus (commençant par un séparateur de chemin). - Relatifs du fichiers qui les inclut (commençant par `./` ou `../`). - - Relatif au répertoire `docs_dir`. Par exemple, si votre `docs_dir` est + - Relatif au répertoire [`docs_dir`]. Par exemple, si votre `docs_dir` est _./docs/_, alors `includes/header.md` va correspondre au fichier *_./docs/includes/header.md_*. - Globs génériques Bash correspondant à plusieurs fichiers locaux. @@ -276,3 +279,4 @@ autorisations][cibuildwheel-470] pour séparer ce plugin de la documentation de [es-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/es/README.md [fr-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/fr/README.md [Bash wildcard globs]: https://facelessuser.github.io/wcmatch/glob/#syntax +[`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir diff --git a/locale/fr/README.md.po b/locale/fr/README.md.po index 31c8298..d7f3959 100644 --- a/locale/fr/README.md.po +++ b/locale/fr/README.md.po @@ -37,9 +37,6 @@ msgstr "" "Inclut contenu des Markdown fichiers, en utilisant éventuellement deux " "délimiteurs pour filtrer le contenu à inclure." -msgid "Examples" -msgstr "Exemples" - msgid "Includes the content of a file or a group of files." msgstr "Inclus le contenu d'un fichier ou d'un groupe de fichiers." @@ -279,15 +276,6 @@ msgstr "" msgid "Configuration" msgstr "Configuration" -msgid "" -"# **opening_tag** and " -"**closing_tag**: The default opening and closing tags. By default are `{%` " -"and `%}`." -msgstr "" -"# **opening_tag** and " -"**closing_tag**: Les balises d'ouverture et de fermeture par défaut. Par " -"défaut sont `{%` et `%}`." - msgid "" "The global behaviour of the plugin can be customized in the configuration." msgstr "" @@ -364,24 +352,6 @@ msgid "" msgstr "" "[Bash wildcard globs]: https://facelessuser.github.io/wcmatch/glob/#syntax" -msgid "" -"# **exclude**: " -"Define global exclusion wildcard patterns. Relative paths defined here will " -"be relative to the *docs/* directory." -msgstr "" -"# **exclude**: " -"Définissez des modèles génériques d'exclusion globale. Les chemins de " -"fichiers relatifs définis ici seront relatifs au répertoire *docs/*." - -msgid "" -"# **cache**: Define a " -"expiration time in seconds for cached HTTP requests when including from " -"URLs." -msgstr "" -"# **cache**: Définissez " -"un délai d'expiration en secondes pour les requêtes HTTP mises en cache lors" -" de l'inclusion d'URL." - msgid "" "Relative from the file that includes them (starting with `./` or `../`)." msgstr "Relatifs du fichiers qui les inclut (commençant par `./` ou `../`)." @@ -395,11 +365,42 @@ msgstr "" "installée. Vous pouvez l'inclure dans l'installation du plugin en ajoutant " "le supplément `cache`:" +msgid "`opening_tag` and `closing_tag`" +msgstr "`opening_tag` et `closing_tag`" + +msgid "" +"Default opening and closing tags. When not specified they are `{%` and `%}`." +msgstr "" +"Balises d'ouverture et de fermeture par défaut. Lorsqu'elles ne sont pas " +"spécifiées, elles sont `{%` et `%}`." + +msgid "" +"Global exclusion wildcard patterns. Relative paths defined here will be " +"relative to the [`docs_dir`] directory." +msgstr "" +"Modèles de globes d'exclusion globaux. Les chemins relatifs définis ici " +"seront relatifs au répertoire [`docs_dir`]." + +msgid "" +"Expiration time in seconds for cached HTTP requests when including from " +"URLs." +msgstr "" +"Délai d'expiration en secondes pour les requêtes HTTP mises en cache lors de" +" l'inclusion d'URL." + +msgid "" +"[`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir" +msgstr "" +"[`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir" + +msgid "Examples" +msgstr "Exemples" + msgid "" -"Relative to the `docs_dir` directory. For instance if your `docs_dir` is " +"Relative to the [`docs_dir`] directory. For instance if your `docs_dir` is " "*./docs/*, then `includes/header.md` will match the file " -"*./docs/includes/header.md*`." +"*./docs/includes/header.md*." msgstr "" -"Relatif au répertoire `docs_dir`. Par exemple, si votre `docs_dir` est " +"Relatif au répertoire [`docs_dir`]. Par exemple, si votre `docs_dir` est " "_./docs/_, alors `includes/header.md` va correspondre au fichier " "*_./docs/includes/header.md_*."