[Docs] - Added a documentation website. (#55)

.github/workflows/build_docs.yml

@@ -0,0 +1,52 @@
+name: Build and deploy documentation website
+on:
+  push:
+    branches:
+      main
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./doc/website
+    steps:
+      # Checkout the repository
+      - uses: actions/checkout@v3
+
+      # Setup a Dart environment
+      - uses: dart-lang/setup-dart@v1
+
+      # Download all the packages that the app uses
+      - run: dart pub get
+
+      # Build the static site
+      - run: dart run bin/dart_rss_docs.dart
+        env:
+          GHUB_DOC_WEBSITE_TOKEN: ${{ vars.GHUB_DOC_WEBSITE_TOKEN }}
+
+      # Zip and upload the static site.
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: ./doc/website/build
+
+  deploy:
+    name: Deploy
+    needs: build
+    runs-on: ubuntu-latest
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

analysis_options.yaml

@@ -1,5 +1,9 @@
 include: package:lints/recommended.yaml
 
+analyzer:
+  exclude:
+    - doc/**
+
 linter:
   rules:
     - always_use_package_imports

doc/website/.gitignore

@@ -0,0 +1,11 @@
+# Build output
+/build
+
+# https://dart.dev/guides/libraries/private-files
+# Created by `dart pub`
+.dart_tool/
+
+# Android Studio and IntelliJ IDEA
+.idea
+
+.DS_Store

doc/website/analysis_options.yaml

@@ -0,0 +1,30 @@
+# This file configures the static analysis results for your project (errors,
+# warnings, and lints).
+#
+# This enables the 'recommended' set of lints from `package:lints`.
+# This set helps identify many issues that may lead to problems when running
+# or consuming Dart code, and enforces writing Dart using a single, idiomatic
+# style and format.
+#
+# If you want a smaller set of lints you can change this to specify
+# 'package:lints/core.yaml'. These are just the most critical lints
+# (the recommended set includes the core lints).
+# The core lints are also what is used by pub.dev for scoring packages.
+
+include: package:lints/recommended.yaml
+
+# Uncomment the following section to specify additional rules.
+
+# linter:
+#   rules:
+#     - camel_case_types
+
+# analyzer:
+#   exclude:
+#     - path/to/excluded/files/**
+
+# For more information about the core and recommended set of lints, see
+# https://dart.dev/go/core-lints
+
+# For additional information about configuring this file, see
+# https://dart.dev/guides/language/analysis-options

doc/website/bin/dart_rss_docs.dart

@@ -0,0 +1,32 @@
+import 'dart:io';
+
+import 'package:static_shock/static_shock.dart';
+
+Future<void> main(List<String> arguments) async {
+  // Configure the static website generator.
+  final staticShock = StaticShock()
+    // Here, you can directly hook into the StaticShock pipeline. For example,
+    // you can copy an "images" directory from the source set to build set:
+    ..pick(DirectoryPicker.parse("images"))
+    // All 3rd party behavior is added through plugins, even the behavior
+    // shipped with Static Shock.
+    ..plugin(const MarkdownPlugin())
+    ..plugin(const JinjaPlugin())
+    ..plugin(const PrettyUrlsPlugin())
+    ..plugin(const RedirectsPlugin())
+    ..plugin(const SassPlugin())
+    ..plugin(DraftingPlugin(
+      showDrafts: arguments.contains("preview"),
+    ))
+    ..plugin(const PubPackagePlugin({
+      "dart_rss",
+    }))
+    ..plugin(
+      GitHubContributorsPlugin(
+        authToken: Platform.environment["github_doc_website_token"],
+      ),
+    );
+
+  // Generate the static website.
+  await staticShock.generateSite();
+}

doc/website/pubspec.yaml

@@ -0,0 +1,14 @@
+name: dart_rss_docs
+description: Documentation for Dart RSS
+version: 1.0.0
+publish_to: none
+
+environment:
+  sdk: ^3.0.0
+
+dependencies:
+  static_shock: any
+
+dev_dependencies:
+  lints: ^2.0.0
+  test: ^1.21.0

doc/website/source/_data.yaml

@@ -0,0 +1,21 @@
+homepage_url: https://flutter-bounty-hunters.github.io/dart-rss/
+
+# Configuration for the package that this website documents.
+package:
+  name: dart_rss
+  title: Dart RSS
+  description: RSS parser and serializer for Dart
+  type: dart
+  is_on_pub: true
+  github:
+    url: https://github.com/flutter-bounty-Hunters/dart-rss
+    organization: flutter-bounty-hunters
+    name: dart-rss
+  discord: https://discord.gg/8hna2VD32s
+  sponsorship: https://flutterbountyhunters.com
+
+# Configuration of the GitHub plugin for loading info about GitHub repositories.
+github:
+  contributors:
+    repositories:
+      - { organization: flutter-bounty-hunters, name: dart-rss }

doc/website/source/_includes/components/code_two_column.jinja

@@ -0,0 +1,56 @@
+<div class="container">
+<div class="row">
+<div class="col-md-6 col-sm-12">
+<h3>With Flutter Test Robots</h3>
+<pre><code>testWidgets((tester) async {
+  // Setup the test.
+
+  // Press CMD+V (like for a paste).
+  await tester.pressCmdV();
+
+  // Press CMD+ALT+LEFT (jump to start).
+  await tester.pressCmdAltLeftArrow();
+
+  // Verify expectations.
+});
+</code></pre>
+</div>
+<div class="col-md-6 col-sm-12">
+<h3>With Flutter</h3>
+<pre><code>testWidgets((tester) async {
+  // Setup the test.
+
+  // Press CMD+V (like for a paste).
+  await tester.sendKeyDownEvent(
+    LogicalKeyboardKey.meta,
+  );
+  await tester.sendKeyEvent(
+    LogicalKeyboardKey.keyV,
+  );
+  await tester.sendKeyUpEvent(
+    LogicalKeyboardKey.meta,
+  );
+
+  // Press CMD+ALT+LEFT (jump to start).
+  await tester.sendKeyDownEvent(
+    LogicalKeyboardKey.meta,
+  );
+  await tester.sendKeyDownEvent(
+    LogicalKeyboardKey.alt,
+  );
+  await tester.sendKeyEvent(
+    LogicalKeyboardKey.left,
+  );
+  await tester.sendKeyUpEvent(
+    LogicalKeyboardKey.left,
+  );
+  await tester.sendKeyUpEvent(
+    LogicalKeyboardKey.meta,
+  );
+
+  // Verify expectations.
+});
+</code></pre>
+</div>
+</div>
+</div>

doc/website/source/_includes/components/contributors.jinja

@@ -0,0 +1,21 @@
+<ol style="display: flex; flex-wrap: wrap; justify-content: center; list-style-type: none; margin: 0; margin-top: 32px; padding: 0; text-align: center;">
+  {% set contributors = github["flutter-bounty-hunters"]["dart-rss"] %}
+  {% set contributorCount = 15 %}
+  {% for contributor in contributors|take(contributorCount) %}
+  <li style="display: inline-block; margin: 0; margin-right: 16px; margin-bottom: 16px; padding: 0;">
+    <a
+        href="{{ contributor.userUrl }}"
+        target="_blank"
+        title="{{ contributor.userId }}"
+        style="display: inline-block; width: 64px; height: 64px; border-radius: 32px; background-image: url('{{ contributor.avatarUrl }}'); background-size: cover; background-repeat: no-repeat; background-position: 50% 50%;"></a>
+  </li>
+  {% endfor %}
+
+  {% if contributors|length > contributorCount %}
+  <li style="display: inline-block; margin: 0; padding: 0;">
+    <div style="display: inline-block; margin: 0; padding: 0; width: 64px; height: 64px; border-radius: 32px; background: rgba(255, 255, 255, 0.05); line-height: 64px; text-align: center; vertical-align: middle;">
+      +{{  contributors|length - contributorCount  }}
+    </div>
+  </li>
+  {% endif %}
+</ol>

doc/website/source/_includes/layouts/homepage.jinja

@@ -0,0 +1,131 @@
+<!doctype html>
+
+<html lang="en" data-bs-theme="dark" data-theme="dark">
+<head>
+  <meta charset="utf-8">
+  <title>{{ package.title }}</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+
+  {% if package.type == "dart" %}
+  <!-- Dart favicon -->
+  <link rel="apple-touch-icon" sizes="180x180" href="images/favicon/dart/apple-touch-icon.png">
+  <link rel="icon" type="image/png" sizes="32x32" href="images/favicon/dart/favicon-32x32.png">
+  <link rel="icon" type="image/png" sizes="16x16" href="images/favicon/dart/favicon-16x16.png">
+  <link rel="manifest" href="images/favicon/dart/site.webmanifest">
+  <link rel="shortcut icon" href="images/favicon/dart/favicon.ico">
+  <meta name="msapplication-TileColor" content="#da532c">
+  <meta name="msapplication-config" content="images/favicon/dart/browserconfig.xml">
+  <meta name="theme-color" content="#ffffff">
+  {% endif %}
+
+  {% if package.type == "flutter" %}
+  <!-- Flutter favicon -->
+  <link rel="apple-touch-icon" sizes="180x180" href="images/favicon/flutter/apple-touch-icon.png">
+  <link rel="icon" type="image/png" sizes="32x32" href="images/favicon/flutter/favicon-32x32.png">
+  <link rel="icon" type="image/png" sizes="16x16" href="images/favicon/flutter/favicon-16x16.png">
+  <link rel="manifest" href="images/favicon/flutter/site.webmanifest">
+  <link rel="mask-icon" href="images/favicon/flutter/safari-pinned-tab.svg" color="#5bbad5">
+  <link rel="shortcut icon" href="images/favicon/flutter/favicon.ico">
+  <meta name="msapplication-TileColor" content="#da532c">
+  <meta name="msapplication-config" content="images/favicon/flutter/browserconfig.xml">
+  <meta name="theme-color" content="#ffffff">
+  {% endif %}
+
+  <!-- Open Graph Social Media -->
+  <meta property="og:url" content="{{ homepage_url }}" />
+  <meta property="og:title" content="{{ package.title }}" />
+  <meta property="og:description" content="{{ package.description }}" />
+  <meta property="og:image" content="{{ homepage_url }}images/branding/social.png" />
+  <meta property="og:type" content="website" />
+
+  <!-- Twitter -->
+  <meta name="twitter:card" content="summary_large_image" />
+  <meta name="twitter:site" content="@FlutterBounties" />
+  <meta name="twitter:url" content="{{ homepage_url }}" />
+  <meta name="twitter:title" content="{{ package.title }}" />
+  <meta name="twitter:description" content="{{ package.description }}" />
+  <meta name="twitter:image" content="{{ homepage_url }}images/branding/social.png" />
+
+  <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-QWTKZyjpPEjISv5WaRU9OFeRpok6YctnYmDr5pNlyT2bRjXh0JMhjY6hW+ALEwIH" crossorigin="anonymous">
+  <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js" integrity="sha384-YvpcrYf0tY3lHB60NNkmXc5s9fDVZLESaAA55NDzOxhy9GkcIdslK1eN7N6jIeHz" crossorigin="anonymous"></script>
+
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Akshar:[email protected]&family=Cutive+Mono&family=Fira+Mono:wght@400;500;700&family=Knewave&display=swap" rel="stylesheet">
+
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css" type="text/css">
+
+  <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/styles/obsidian.min.css">
+  <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/highlight.min.js"></script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/dart.min.js"></script>
+  <script>hljs.highlightAll();</script>
+
+  <link rel="stylesheet" href="styles/homepage.css">
+</head>
+
+<body>
+  <div id="hero">
+    <div class="top-gap">&nbsp;</div>
+
+    {% if package.type == "flutter" %}
+    <img id="flutterLogo" src="images/branding/flutter-logo.svg" height="48">
+    {% else %}
+    <img id="dartLogo" src="images/branding/dart-logo.svg" height="48">
+    {% endif %}
+
+    <span class="title">{{ package.title }}</span>
+    <span class="subtitle">{{ package.description }}</span>
+
+    <div class="middle-gap">&nbsp;</div>
+
+    <div class="latest-version" onclick="copy('{{ package.name }}: ^{{ pub.dart_rss.version }}')">
+      <span class="dependency-declaration">
+        <span class="name">{{ package.name }}:&nbsp;</span><span class="version">^{{ pub.dart_rss.version }}</span>
+      </span>
+      <a class="copy-button">
+        <i class="fa-solid fa-copy"></i>
+      </a>
+    </div>
+
+    <div class="social-buttons">
+      {% if package.github != null %}
+      <a href="{{ package.github.url }}" target="_blank" type="button" class="btn btn-primary"><i class="fa-brands fa-github"></i> GitHub</a>
+      {% endif %}
+
+      {% if package.discord != null %}
+      <a href="{{ package.discord }}" target="_blank" type="button" class="btn btn-primary"><i class="fa-brands fa-discord"></i> Discord</a>
+      {% endif %}
+
+      {% if package.sponsorship != null %}
+      <a href="{{ package.sponsorship }}" target="_blank" type="button" class="btn btn-primary"><i class="fa-solid fa-dollar-sign"></i> Sponsor</a>
+      {% endif %}
+
+      <a href="https://pub.dev/packages/{{ package.name }}" target="_blank" type="button" class="btn btn-primary">Pub</a>
+    </div>
+
+    <div class="bottom-gap">&nbsp;</div>
+
+    <div class="built-with-static-shock">
+      This website was built with <a href="https://staticshock.io" target="_blank" class="static-shock">Static Shock!</a>
+    </div>
+  </div>
+
+  <div class="container">
+    <!-- Page/article content -->
+    <main class="col-12 col-lg-10 col-xl-8">
+      {{   content   }}
+    </main>
+  </div>
+
+  <footer>
+    You can generate a documentation website just like this one, with <a href="https://staticshock.io" target="_blank" class="static-shock">Static Shock</a>
+  </footer>
+
+  <script>
+    function copy(text) {
+    console.log("Copying text: '" + text + "'");
+      navigator.clipboard.writeText(text);
+    }
+  </script>
+</body>
+</html>