docs: updated workflows examples and options descriptions (#772) [skip ci]

2022-01-14 04:49:14 +01:00
parent 44e3992ca9
commit 4d06539136
80 changed files with 2292 additions and 450 deletions
--- a/source/plugins/music/README.md
+++ b/source/plugins/music/README.md
@@ -205,61 +205,121 @@ Click on the Name of any matching request. In the “Headers” tab, scroll to t

 </details>

+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_music` | `boolean` **[no]** | Display your music tracks |
+| `plugin_music_provider` | `string` **[]** *{"apple", "spotify", "lastfm", "youtube"}* | Music provider |
+| `plugin_music_token` 🔐 | `token` **[]** | Music provider personal token |
+| `plugin_music_mode` | `string` **[]** *{"playlist", "recent", "top"}* | Plugin mode |
+| `plugin_music_playlist` | `string` **[]** | Embed playlist url |
+| `plugin_music_limit` | `number` **[4]** *{1 ≤ 𝑥 ≤ 100}* | Maximum number of tracks to display |
+| `plugin_music_played_at` | `boolean` **[no]** | Display when the track was played |
+| `plugin_music_time_range` | `string` **[short]** *{"short", "medium", "long"}* | Time period for top mode |
+| `plugin_music_top_type` | `string` **[tracks]** *{"tracks", "artists"}* | Whether to show tracks or artists in top mode |
+| `plugin_music_user` | `string` **[.user.login]** | Music provider username |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows

-[➡️ Available options for this plugin](metadata.yml)
-
-##### Recent
-
+<!--examples-->
 ```yaml
- uses: lowlighter/metrics@latest
-  with:
-    # ... other options
-    plugin_music: yes
-    plugin_music_provider: spotify # Use Spotify as provider
-    plugin_music_mode: recent      # Set plugin mode
-    plugin_music_limit: 4          # Limit to 4 entries
-    plugin_music_played_at: yes    # Show timestamp (for spotify only)
-    plugin_music_token: "${{ secrets.SPOTIFY_CLIENT_ID }}, ${{ secrets.SPOTIFY_CLIENT_SECRET }}, ${{ secrets.SPOTIFY_REFRESH_TOKEN }}"
-```
+name: Apple Music - Random track from playlist
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.music.playlist.svg
+  token: NOT_NEEDED
+  plugin_music: 'yes'
+  plugin_music_playlist: https://embed.music.apple.com/fr/playlist/usr-share/pl.u-V9D7m8Etjmjd0D
+  plugin_music_limit: 2

+```
 ```yaml
- uses: lowlighter/metrics@latest
-  with:
-    # ... other options
-    plugin_music: yes
-    plugin_music_provider: lastfm  # Use Last.fm as provider
-    plugin_music_mode: recent      # Set plugin mode
-    plugin_music_limit: 4          # Limit to 4 entries
-    plugin_music_user: .user.login # Use same username as GitHub login
-    plugin_music_token: ${{ secrets.LASTFM_API_KEY }}
+name: Spotify - Random track from playlist
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.music.playlist.spotify.svg
+  token: NOT_NEEDED
+  plugin_music: 'yes'
+  plugin_music_playlist: https://open.spotify.com/embed/playlist/3nfA87oeJw4LFVcUDjRcqi
+
 ```
-
-##### Top
-
 ```yaml
- uses: lowlighter/metrics@latest
-  with:
-    # ... other options
-    plugin_music: yes
-    plugin_music_provider: spotify # Use Spotify as provider
-    plugin_music_mode: top         # Set plugin mode
-    plugin_music_limit: 4          # Limit to 4 entries, maximum is 50 for "top" mode with spotify
-    plugin_music_top_type: tracks  # Set type for "top" mode; either tracks or artists
-    plugin_music_time_range: short # Set time range for "top" mode; either short (4 weeks), medium (6 months) or long (several years)
-    plugin_music_token: "${{ secrets.SPOTIFY_CLIENT_ID }}, ${{ secrets.SPOTIFY_CLIENT_SECRET }}, ${{ secrets.SPOTIFY_REFRESH_TOKEN }}"
-```
+name: Spotify - Recently listed
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.music.recent.svg
+  token: NOT_NEEDED
+  plugin_music: 'yes'
+  plugin_music_provider: spotify
+  plugin_music_mode: recent
+  plugin_music_token: ${{ secrets.SPOTIFY_TOKENS }}
+  plugin_music_limit: 2

-```yaml
- uses: lowlighter/metrics@latest
-  with:
-    # ... other options
-    plugin_music: yes
-    plugin_music_provider: lastfm  # Use Last.fm as provider
-    plugin_music_mode: top         # Set plugin mode
-    plugin_music_limit: 4          # Limit to 4 entries
-    plugin_music_top_type: artists # Set type for "top" mode; either tracks or artists
-    plugin_music_time_range: long  # Set time range for "top" mode; either short (4 weeks), medium (6 months) or long (several years)
-    plugin_music_user: .user.login # Use same username as GitHub login
-    plugin_music_token: ${{ secrets.LASTFM_API_KEY }}
 ```
+```yaml
+name: Spotify - Top tracks
+uses: lowlighter/metrics@latest
+with:
+  token: NOT_NEEDED
+  plugin_music: 'yes'
+  plugin_music_mode: top
+  plugin_music_provider: spotify
+  plugin_music_time_range: short
+  plugin_music_top_type: tracks
+
+```
+```yaml
+name: Spotify - Top artists
+uses: lowlighter/metrics@latest
+with:
+  token: NOT_NEEDED
+  plugin_music: 'yes'
+  plugin_music_mode: top
+  plugin_music_provider: spotify
+  plugin_music_time_range: long
+  plugin_music_top_type: artists
+
+```
+```yaml
+name: Youtube Music - Random track from playlist
+uses: lowlighter/metrics@latest
+with:
+  token: NOT_NEEDED
+  plugin_music: 'yes'
+  plugin_music_playlist: >-
+    https://music.youtube.com/playlist?list=OLAK5uy_kU_uxp9TUOl9zVdw77xith8o9AknVwz9U
+
+```
+```yaml
+name: Youtube Music - Recently listed
+uses: lowlighter/metrics@latest
+with:
+  token: NOT_NEEDED
+  plugin_music_token: ${{ secrets.YOUTUBE_MUSIC_TOKENS }}
+  plugin_music: 'yes'
+  plugin_music_mode: recent
+  plugin_music_provider: youtube
+
+```
+```yaml
+name: Last.fm  - Recently listed
+uses: lowlighter/metrics@latest
+with:
+  token: NOT_NEEDED
+  plugin_music_token: ${{ secrets.LASTFM_TOKEN }}
+  plugin_music: 'yes'
+  plugin_music_provider: lastfm
+  plugin_music_user: RJ
+
+```
+<!--/examples-->
--- a/source/plugins/music/examples.yml
+++ b/source/plugins/music/examples.yml
@@ -0,0 +1,82 @@
+- name: Apple Music - Random track from playlist
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.music.playlist.svg
+    token: NOT_NEEDED
+    plugin_music: yes
+    plugin_music_playlist: https://embed.music.apple.com/fr/playlist/usr-share/pl.u-V9D7m8Etjmjd0D
+    plugin_music_limit: 2
+
+- name: Spotify - Random track from playlist
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.music.playlist.spotify.svg
+    token: NOT_NEEDED
+    plugin_music: yes
+    plugin_music_playlist: https://open.spotify.com/embed/playlist/3nfA87oeJw4LFVcUDjRcqi
+
+- name: Spotify - Recently listed
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.music.recent.svg
+    token: NOT_NEEDED
+    plugin_music: yes
+    plugin_music_provider: spotify
+    plugin_music_mode: recent
+    plugin_music_token: ${{ secrets.SPOTIFY_TOKENS }}
+    plugin_music_limit: 2
+  test:
+    plugin_music_token: MOCKED_CLIENT_ID, MOCKED_CLIENT_SECRET, MOCKED_REFRESH_TOKEN
+
+- name: Spotify - Top tracks
+  uses: lowlighter/metrics@latest
+  with:
+    token: NOT_NEEDED
+    plugin_music: yes
+    plugin_music_mode: top
+    plugin_music_provider: spotify
+    plugin_music_time_range: short
+    plugin_music_top_type: tracks
+  test:
+    plugin_music_token: MOCKED_CLIENT_ID, MOCKED_CLIENT_SECRET, MOCKED_REFRESH_TOKEN
+
+- name: Spotify - Top artists
+  uses: lowlighter/metrics@latest
+  with:
+    token: NOT_NEEDED
+    plugin_music: yes
+    plugin_music_mode: top
+    plugin_music_provider: spotify
+    plugin_music_time_range: long
+    plugin_music_top_type: artists
+  test:
+    plugin_music_token: MOCKED_CLIENT_ID, MOCKED_CLIENT_SECRET, MOCKED_REFRESH_TOKEN
+
+- name: Youtube Music - Random track from playlist
+  uses: lowlighter/metrics@latest
+  with:
+    token: NOT_NEEDED
+    plugin_music: yes
+    plugin_music_playlist: https://music.youtube.com/playlist?list=OLAK5uy_kU_uxp9TUOl9zVdw77xith8o9AknVwz9U
+
+- name: Youtube Music - Recently listed
+  uses: lowlighter/metrics@latest
+  with:
+    token: NOT_NEEDED
+    plugin_music_token: ${{ secrets.YOUTUBE_MUSIC_TOKENS }}
+    plugin_music: yes
+    plugin_music_mode: recent
+    plugin_music_provider: youtube
+  test:
+    plugin_music_token: SAPISID=MOCKED_COOKIE; OTHER_PARAM=OTHER_VALUE;
+
+- name: Last.fm  - Recently listed
+  uses: lowlighter/metrics@latest
+  with:
+    token: NOT_NEEDED
+    plugin_music_token: ${{ secrets.LASTFM_TOKEN }}
+    plugin_music: yes
+    plugin_music_provider: lastfm
+    plugin_music_user: RJ
+  test:
+    plugin_music_token: MOCKED_TOKEN