feat: add rss support

Create daily, weekly, monthly and yearly RSS feeds of the site changes

docs: explain how to create the newsletters automatically

chore: update requirements

feat: create newsletter landing page

docs/adr/002-initial_plugin_design.md

@@ -25,7 +25,7 @@ The plugin will consist on the following phases:
 * [Build the MkDocs nav with the newsletter articles](004-article_newsletter_structure.md)
 * Decide which changes need to be notified
 * Send the notifications:
-    * Update the RSS
+    * [Update the RSS](006-rss_feed_creation.md)
     * Send the email.
 
 # Decision

docs/adr/004-article_newsletter_structure.md

@@ -21,7 +21,7 @@ similar to:
 
 ```yaml
 Newsletters:
-    - newsletter/0_index.md
+    - newsletter/0_newsletter_index.md
     - 2020:
         - newsletter/2020.md
         - February of 2020:
@@ -42,10 +42,10 @@ Newsletters:
 
 Where:
 
-* `0_index.md`: Is the landing page of the newsletters. It's prepended with `0_`
-    so it shows the first item when you do `ls` in the directory. It will be
-    created from a template the first time you run it, then you can change the
-    file to fit your liking.
+* `0_newsletter_index.md`: Is the landing page of the newsletters. It's
+    prepended with `0_` so it shows the first item when you do `ls` in the
+    directory. It will be created from a template the first time you run it,
+    then you can change the file to fit your liking.
 * `2020.md`: Is an automatic year summary done at the end of the year.
 * `2020_01.md`: Is an automatic month summary for the monthly rss done at the end
     of the month joining the changes of the month weeks.

docs/adr/006-rss_feed_creation.md

@@ -0,0 +1,59 @@
+Date: 2021-03-26
+
+# Status
+<!-- What is the status? Draft, Proposed, Accepted, Rejected, Deprecated or Superseded?
+-->
+Draft
+
+# Context
+<!-- What is the issue that we're seeing that is motivating this decision or change? -->
+We want the readers to be notified by RSS of the changes of the documentation
+site. They should be able to choose the frequency of the updates.
+
+# Proposals
+<!-- What are the possible solutions to the problem described in the context -->
+
+Once the newsletter mkdocs articles are created, we need to expose them through
+RSS feeds for each of the periodicities (daily, weekly, monthly and yearly).
+
+We have the newsletter articles both in markdown and in html if we use the
+[`on_post_build`](https://www.mkdocs.org/user-guide/plugins/#on_post_build)
+event.
+
+We need to create both the RSS site documentation and the entries content. The
+first one can be created with the contents of the mkdocs `config` object, the
+second ones using the html might be more interesting as it will have already the
+internal links resolved to working urls.
+
+We'll refactor the code from
+[mkdocs-rss-plugin](https://github.com/Guts/mkdocs-rss-plugin), as they've
+already solved the problem of creating an RSS for a MkDocs site.
+
+We need to decide:
+
+* [How to select the newsletters to be published in each
+    feed.](#newsletter-selection)
+* [How to create each feed.](#how-to-create-each-feed)
+
+## Newsletter selection
+
+We're going to expose 15 entries in each feed.
+
+To get the 15 last newsletters for each feed we need to analyze the existent
+elements in the newsletter directory and then see the latest modification date
+of each of them.
+
+The `published_date` of the channel must be the published date of the last entry
+of the feed.
+
+## How to create each feed
+
+We'll use the mkdocs-rss-plugin jinja2 template. I tried to use feedparser, but
+it's only for parsing and not for building RSSs.
+
+# Decision
+<!-- What is the change that we're proposing and/or doing? -->
+Implement the only proposal.
+
+# Consequences
+<!-- What becomes easier or more difficult to do because of this change? -->

docs/adr/adr.md

@@ -9,11 +9,13 @@ graph TD
     003[003: Selected changes to record]
     004[004: Article newsletter structure]
     005[005: Article newsletter creation]
+    006[006: RSS feed creation]
 
     001 -- Extended --> 002
     002 -- Extended --> 003
     002 -- Extended --> 004
     002 -- Extended --> 005
+    002 -- Extended --> 006
     003 -- Extended --> 004
     004 -- Extended --> 005
 
@@ -22,12 +24,14 @@ graph TD
     click 003 "https://lyz-code.github.io/mkdocs-newsletter/adr/003-select_the_changes_to_record" _blank
     click 004 "https://lyz-code.github.io/mkdocs-newsletter/adr/004-article_newsletter_structure" _blank
     click 005 "https://lyz-code.github.io/mkdocs-newsletter/adr/005-create_the_newsletter_articles" _blank
+    click 006 "https://lyz-code.github.io/mkdocs-newsletter/adr/006-rss_feed_creation" _blank
 
     001:::accepted
     002:::accepted
     003:::accepted
     004:::accepted
     005:::accepted
+    006:::draft
 
     classDef draft fill:#CDBFEA;
     classDef proposed fill:#B1CCE8;

docs/index.md

@@ -9,7 +9,9 @@ It creates daily, weekly, monthly and yearly newsletter articles with the
 changes of each period. Those pages, stored under the `Newsletters` section, are
 filled with the changes extracted from the git history and the commit messages.
 The changes are grouped by categories, subcategories and then by file using the
-order of the site's navigation structure.
+order of the site's navigation structure. [RSS feeds](rss_feeds.md) are also
+created for each newsletter type, so it's easy for people to keep updated with
+the evolution of the site.
 
 It assumes that you're using [semantic versioning](https://semver.org/) or our
 [enhanced version](#commit-message-guidelines) to create your commits. Only
@@ -20,146 +22,32 @@ workflow doesn't feel good.
 
 ![ ](screencast.gif)
 
-Check [the live
-version](https://lyz-code.github.io/blue-book/newsletter/2021_02).
+Check [a live
+version](https://lyz-code.github.io/blue-book/newsletter).
 
-# Installing
+# Alternatives
 
-```bash
-pip install mkdocs-newsletter
-```
+## [mkdocs-rss-plugin](https://github.com/Guts/mkdocs-rss-plugin)
 
-To enable this plugin, you need to declare it in your config file `mkdocs.yml`.
+This cool plugin creates two RSS feeds for the changes of the git history, one
+for new files and another for updated ones.
 
-```yaml
-plugins:
-  - autolinks
-  - section-index
-  - mkdocs-newsletter
-```
+Creating an RSS entry for each change, it's not the ideal solution for digital
+gardens because:
 
-We rely on
-[mkdocs-autolink-plugin](https://github.com/midnightprioriem/mkdocs-autolinks-plugin)
-to create the links between the articles and on
-[mkdocs-section-index](https://github.com/oprypin/mkdocs-section-index/) to make
-the sections clickable.
+* *The user will receive too many updates*: In a normal day, you can edit up to
+    10 files, which will create 10 RSS entries. That can annoy the user so it
+    will stop reading your feed.
+* *The user will receive updates on irrelevant content*: As an entry is created
+    for each change, styling and grammar corrections are sent as a new full
+    entry.
+* *The user receives no context of the change*: The RSS entry links to the
+    article but not it's sections, so if you frequently edit a big file, the,
+    the user will see no point on the entry and skip it and in the end drop the
+    RSS.
 
-# Usage
-
-Every time you build the site, the plugin will inspect the git history and
-create the new newsletter articles under the `docs/newsletter` directory and
-configure the `Newsletter` section.
-
-The entrypoints for the authors are:
-
-* [Writing the commit messages](#commit-message-guidelines).
-* [Manually changing the created newsletter
-    articles](#manual-newsletter-changes): to fix errors.
-
-## Commit message guidelines
-
-The plugin assumes that you're using the [Angular semantic versioning
-format](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)
-to create the commits. Adapted to a documentation repository such as the [digital
-gardens](https://lyz-code.github.io/blue-book/digital_garden/), the structure
-would be:
-
-```
-{type_of_change}({file_changed}): {short_description}
-
-{full_description}
-```
-
-Where:
-
-* `type_of_change` is one of:
-
-    * `feat`: Add new content to the repository, it can be a new file or new content on an
-    existent file.
-    * `fix`: Correct existing content.
-    * `perf`: Improve existing content.
-    * `refactor`: Reorder the articles content.
-    * `style`: Correct grammar, orthography or broken links.
-    * `ci`: Change the continuous integration pipelines.
-    * `chore`: Update the dependencies required to build the site.
-
-* `file_changed`: Name of the changed file (without the `.md` extension).
-* `short_description`: A succinct description of the change. It doesn't need to
-    start with a capitalize letter nor end with a dot.
-* `full_description`: A summary of the added changes.
-
-For example:
-
-```
-feat(adr): introduce the Architecture Decision Records
-
-[ADR](https://github.com/joelparkerhenderson/architecture_decision_record) are
-short text documents that captures an important architectural decision made
-along with its context and consequences.
-```
-
-Only changes of type `feat`, `fix`, `perf` or `refactor` will be added to the
-newsletter. The reader is not interested in the others.
-
-### Multiple changes in the same commit
-
-When growing [digital
-gardens](https://lyz-code.github.io/blue-book/digital_garden/), it's normal to
-do many small changes on different files. Making a commit for each of them is
-cumbersome and can break your writing flow. That's why the plugin is able to
-parse different changes from the same commit. For example:
-
-```
-feat(pexpect): introduce the pexpect python library
-
-A pure Python module for spawning
-child applications; controlling them; and responding to expected patterns in
-their output. Pexpect works like Don Libes’ Expect. Pexpect allows your script
-to spawn a child application and control it as if a human were typing commands.
-
-style(prompt_toolkit): correct links and indentations
-
-fix(python_snippets): explain how to show the message in custom exceptions
-
-feat(python_snippets): explain how to import a module or object from within a python program
-```
-
-### Link specific parts of the articles
-
-You can specify the section of the article where the change has been made by
-appending the anchor to the file changed. For example:
-
-```
-perf(prometheus_installation#upgrading-notes): Add upgrading notes from 10.x -> 11.1.7
-```
-
-The format of the anchor can be Markdown's default or you can use the user
-friendly one with caps and spaces `perf(prometheus_installation#Upgrading
-notes)`.
-
-### Rich full description content
-
-The `full_description` content will be processed by MkDocs, that means that all
-it's features applies, such as autolinking or admonitions.
-
-~~~markdown
-perf(prometheus_installation): Add upgrading notes from 10.x -> 11.1.7
-
-!!! warning "Don't upgrade to 12.x if you're still using Helm 2."
-
-    [Helm](helm.md#version-2) is deprecated and you should migrate to v3.
-~~~
-
-## Manual newsletter changes
-
-To change the contents of the newsletters directly edit the files under
-`docs/newsletters`.
-
-## Exclude the newsletters from the search
-
-If you don't want to see the newsletters in the result of the search, use the
-[mkdocs-exclude-search](https://pypi.org/project/mkdocs-exclude-search/) plugin
-to exclude all articles under `docs/newsletter`.
+If you feel that your use case wont suffer from those conditions, I suggest you
+use their plugin instead, as it's much easier to use.
 
 # Future plans