Doc: typo & tips (#179)

- Fix typo.

- Update the `.vscode/settings.json` example in `CONTRIBUTING.md`.

  [Venv][venv-doc] uses `bin` on POSIX, but `Scripts` on Windows.

- Some tests won't pass without `requirements/documentation.txt`.

See also:
[4b1cfd](4b1cfdc)
adds `documentation.txt` into GitHub Actions.

For example, `test_simple_build` in `tests/test_build.py` builds
`mkdocs.yml`,
  and its theme (mkdocs-bootswatch/united) is not covered in
  `requirements/development.txt`.

  ```yaml
  theme:
    name: united
  ```

[venv-doc]:
https://docs.python.org/3.11/library/venv.html#how-venvs-work

Author: Guts

CHANGELOG.md

@@ -62,8 +62,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-* Minor improvments: clean unused imports, lines length and use fstrings in logging by @Guts in <https://github.com/Guts/mkdocs-rss-plugin/pull/143>
-* Improvment: more granular fallback to build timestamp by @Guts in <https://github.com/Guts/mkdocs-rss-plugin/pull/144>
+* Minor improvements: clean unused imports, lines length and use fstrings in logging by @Guts in <https://github.com/Guts/mkdocs-rss-plugin/pull/143>
+* Improvement: more granular fallback to build timestamp by @Guts in <https://github.com/Guts/mkdocs-rss-plugin/pull/144>
 
 ## 1.3.0 - 2022-10-07
 
@@ -100,7 +100,7 @@ So, no feature in this release, just focusing on quality and code cleanliness.
 ### Fixed
 
 * Minor bugs fixes
-* Minor documentation improvments
+* Minor documentation improvements
 
 ----
 
@@ -157,7 +157,7 @@ So, no feature in this release, just focusing on quality and code cleanliness.
 
 ### Added
 
-* option to get the full page content into thed. Contributed by [liang2kl](https://github.com/liang2kl) with [PR 88](https://github.com/Guts/mkdocs-rss-plugin/pull/88). See the [related documentation section](https://guts.github.io/mkdocs-rss-plugin/configuration/#item-description-length).
+* option to get the full page content into thread. Contributed by [liang2kl](https://github.com/liang2kl) with [PR 88](https://github.com/Guts/mkdocs-rss-plugin/pull/88). See the [related documentation section](https://guts.github.io/mkdocs-rss-plugin/configuration/#item-description-length).
 
 ### Changed
 
@@ -333,7 +333,7 @@ So, no feature in this release, just focusing on quality and code cleanliness.
 
 ### Changed
 
-* docs: minor improvments
+* docs: minor improvements
 
 ----
 

CONTRIBUTING.md

@@ -17,7 +17,7 @@ Make sure your code *roughly* follows [PEP-8](https://www.python.org/dev/peps/pe
 - docstrings: [sphinx-style](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html#the-sphinx-docstring-format) is used to write technical documentation.
 - formatting: [black](https://black.readthedocs.io/) is used to automatically format the code without debate.
 - sorted imports: [isort](https://pycqa.github.io/isort/) is used to sort imports
-- static analisis: [flake8](https://flake8.pycqa.org/en/latest/) is used to catch some dizziness and keep the source code healthy.
+- static analysis: [flake8](https://flake8.pycqa.org/en/latest/) is used to catch some dizziness and keep the source code healthy.
 
 ----
 
@@ -30,6 +30,8 @@ Feel free to use the IDE you love. Here come configurations for some popular IDE
 ```jsonc
 {
     "python.defaultInterpreterPath": ".venv/bin/python",
+    // 👆 For Windows, change it to "./.venv/Scripts/python.exe".
+    // Or you can manually select one when VS Code asks for it.
     // Editor
     "editor.bracketPairColorization.enabled": true,
     "editor.guides.bracketPairs":"active",

docs/configuration.md

@@ -27,8 +27,8 @@ To produce a valid RSS feed, the plugin uses:
 | [`site_name`](https://www.mkdocs.org/user-guide/configuration/#site_name) | **required** | [`title`](https://www.w3schools.com/xml/rss_tag_title_link_description_channel.asp) and also as [`source` URL label](https://www.w3schools.com/xml/rss_tag_source.asp) for each feed item |
 | [`site_url`](https://www.mkdocs.org/user-guide/configuration/#site_url) | **required** | [`link`](https://www.w3schools.com/xml/rss_tag_title_link_description_channel.asp) |
 | ---- | ---- | ---- |
-| [`repo_url`](https://www.mkdocs.org/user-guide/configuration/#repo_url) | **recomended** | [`docs`](https://www.w3schools.com/xml/rss_tag_docs.asp) |
-| [`site_author`](https://www.mkdocs.org/user-guide/configuration/#site_author) | **recomended** | [`managingEditor`](https://www.w3schools.com/xml/rss_tag_managingeditor.asp) |
+| [`repo_url`](https://www.mkdocs.org/user-guide/configuration/#repo_url) | **recommended** | [`docs`](https://www.w3schools.com/xml/rss_tag_docs.asp) |
+| [`site_author`](https://www.mkdocs.org/user-guide/configuration/#site_author) | **recommended** | [`managingEditor`](https://www.w3schools.com/xml/rss_tag_managingeditor.asp) |
 | ---- | ---- | ---- |
 | [`copyright`](https://www.mkdocs.org/user-guide/configuration/#copyright) | *optional* | [`copyright`](https://www.w3schools.com/xml/rss_tag_copyright.asp) |
 | [`locale` or `theme/locale` or `theme/language`](https://github.com/squidfunk/mkdocs-material/issues/1350#issuecomment-559095892) | *optional* | [`language`](https://www.w3schools.com/xml/rss_tag_language.asp) |
@@ -51,7 +51,7 @@ Basically, each page is an item element in the RSS feed.
 | [`page.canonical_url`](https://github.com/mkdocs/mkdocs/blob/master/mkdocs/structure/pages.py#L97-L105) | **required** and *optional* | mandatory item element [`link`](https://www.w3schools.com/xml/rss_tag_title_link_description_item.asp) and also used as [`guid`](https://www.w3schools.com/xml/rss_tag_guid.asp) |
 | [`page.meta.title`](https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data) | **required** | [`title`](https://www.w3schools.com/xml/rss_tag_title_link_description_item.asp) |
 | [`page.meta.description`](https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data) if present, else extract headlines from the content. See below the [item_description_length option](/configuration/#item-description-length). | **required** | [`description`](https://www.w3schools.com/xml/rss_tag_title_link_description_item.asp) |
-| creation or last update datetime according git log. Can be overridden by dates in page.meta. If not, then it uses [MkDcos build date](https://github.com/mkdocs/mkdocs/blob/master/mkdocs/utils/__init__.py#L111-L118) | **recomended** | [`pubDate`](https://www.w3schools.com/xml/rss_tag_pubdate_item.asp) |
+| creation or last update datetime according git log. Can be overridden by dates in page.meta. If not, then it uses [MkDocs build date](https://github.com/mkdocs/mkdocs/blob/master/mkdocs/utils/__init__.py#L111-L118) | **recommended** | [`pubDate`](https://www.w3schools.com/xml/rss_tag_pubdate_item.asp) |
 | [`page.meta.image`](https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data) | *optional* | item element [`enclosure`](https://www.w3schools.com/xml/rss_tag_enclosure.asp). Some HTTP requests can be performed to retrieve remote images length. |
 | [`page.meta.authors`](https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data) or `page.meta.author`. Accepted value types: `str` `list`, `tuple`. <br />To comply with the standard, the page writer is responsible to fill this field following this syntax: `[email protected] (John Doe)` ([read this SO](https://stackoverflow.com/a/6079731/2556577)). | *optional* | [`author`](https://www.w3schools.com/XML/rss_tag_author.asp) |
 | [`page.meta.tags`](https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data) or any tags value (for example `page.meta.categories`...). Accepted value types: `str` `list`. | *optional* | [`category`](https://www.w3schools.com/xml/rss_tag_category_item.asp) |
@@ -219,7 +219,7 @@ To fill each [item description element](https://www.w3schools.com/xml/rss_tag_ti
 
 - If this value is set to `-1`, then the articles' full HTML content will be filled into the description element.
 - Otherwise, the plugin first tries to retrieve the value of the keyword `description` from the [page metadata].
-- If the value is non-negative and no `description` meta is found, then the plugin retrieves the first number of characters of the page content defined by this setting. Retrieved content is the raw markdown converted rougthly into HTML.
+- If the value is non-negative and no `description` meta is found, then the plugin retrieves the first number of characters of the page content defined by this setting. Retrieved content is the raw markdown converted roughly into HTML.
 
 `abstract_chars_count`: number of characters to use as item description.
 
@@ -299,7 +299,7 @@ So, it's possible to use the dates manually specified into the [page metadata] t
 - `as_update`: meta tag name to use as update date. Default to `False`.
 - `datetime_format`: datetime format. Default to `"%Y-%m-%d %H:%M"`.
 - `default_timezone`: timezone to use by default to make aware datetimes. Default to `UTC`. Introduced in version 1.3.0 with [PR 142](https://github.com/Guts/mkdocs-rss-plugin/pull/142).
-- `default_time`: time to use if page contains only a date. Useful to avoid the 'midnight syndrom' or have to specify hour in every single page. Default to `None`. 24h-clock format is expected: `%H:%M`. Example: `"14:20"`. Introduced in version 1.4.0 with [PR 145](https://github.com/Guts/mkdocs-rss-plugin/pull/145).
+- `default_time`: time to use if page contains only a date. Useful to avoid the 'midnight syndrome' or have to specify hour in every single page. Default to `None`. 24h-clock format is expected: `%H:%M`. Example: `"14:20"`. Introduced in version 1.4.0 with [PR 145](https://github.com/Guts/mkdocs-rss-plugin/pull/145).
 
 #### Example
 
@@ -417,7 +417,7 @@ Default: `None`.
 
 ### Reference RSS feeds in HTML meta-tags
 
-To facilitate the discovery of RSS feeds, it's recomended to add relevant meta-tags into the pages `<head>`, through template customization in `main.html` :
+To facilitate the discovery of RSS feeds, it's recommended to add relevant meta-tags into the pages `<head>`, through template customization in `main.html` :
 
 ```html
 {% extends "base.html" %}

tests/fixtures/mkdocs_simple.yml

@@ -0,0 +1,51 @@
+# Project information
+site_name: MkDocs RSS Plugin
+site_description: Documentation about the MkDocs RSS Plugin
+site_author: [email protected] (Julien M.)
+site_url: https://guts.github.io/mkdocs-rss-plugin/
+copyright: "Guts - In Geo Veritas"
+
+# Repository
+repo_name: "guts/mkdocs-rss-plugin"
+repo_url: "https://github.com/guts/mkdocs-rss-plugin/"
+edit_uri: "blob/main/docs/"
+
+docs_dir: "docs/"
+use_directory_urls: true
+
+plugins:
+  - rss:
+      date_from_meta:
+        as_creation: "date"
+        as_update: false
+        datetime_format: "%Y-%m-%d %H:%M"
+        default_timezone: "Europe/Paris"
+        default_time: "22:00"
+      abstract_chars_count: 160
+      abstract_delimiter: <!-- more -->
+      image: https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Feed-icon.svg/128px-Feed-icon.svg.png
+      match_path: ".*"
+      pretty_print: false
+      url_parameters:
+        utm_source: "documentation"
+        utm_medium: "RSS"
+        utm_campaign: "feed-syndication"
+  - search
+
+theme:
+  name: mkdocs
+  language: en
+
+# Extensions to enhance markdown
+markdown_extensions:
+  - admonition
+  - attr_list
+  - codehilite
+  - meta
+  - toc:
+      permalink: "#"
+
+nav:
+  - "Home": "index.md"
+  - "Settings": "configuration.md"
+  - "Changelog": "changelog.md"

tests/test_build.py

@@ -71,7 +71,7 @@ def test_simple_build(self):
         with tempfile.TemporaryDirectory() as tmpdirname:
             cli_result = self.build_docs_setup(
                 testproject_path="docs",
-                mkdocs_yml_filepath=Path("mkdocs.yml"),
+                mkdocs_yml_filepath=Path("tests/fixtures/mkdocs_simple.yml"),
                 output_path=tmpdirname,
                 strict=False,
             )