Update dev docs (#81)

* Updated documentations for local development

.github/workflows/argos.yaml

@@ -0,0 +1,45 @@
+name: Argos CI Screenshots
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - '.github/workflows/argos.yml'
+      - 'website/**'
+  pull_request:
+    branches: [ master ]
+    types: [ opened, synchronize, reopened ]
+    paths:
+      - '.github/workflows/argos.yml'
+      - 'website/**'
+
+jobs:
+  take-screenshots:
+    defaults:
+      run:
+        working-directory: website
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: current
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Install Playwright browsers
+        run: yarn playwright install --with-deps chromium
+
+      - name: Build the website
+        run: yarn docusaurus build
+
+      - name: Take screenshots with Playwright
+        run: yarn playwright test
+
+      - name: Upload screenshots to Argos
+        run: yarn argos upload ./screenshots

website/README.md

@@ -11,7 +11,7 @@ $ yarn
 ### Local Development
 
 ```
-$ yarn start
+$ yarn start --host=0.0.0.0 --port=3000
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

website/argos/utils.ts

@@ -0,0 +1,17 @@
+import * as cheerio from "cheerio";
+import * as fs from "fs";
+
+export function extractSitemapPathnames(sitemapPath: string): string[] {
+  const sitemap = fs.readFileSync(sitemapPath).toString();
+  const $ = cheerio.load(sitemap, { xmlMode: true });
+  const urls: string[] = [];
+  $("loc").each(function handleLoc() {
+    urls.push($(this).text());
+  });
+  return urls.map((url) => new URL(url).pathname);
+}
+
+// Converts a pathname to a decent screenshot name
+export function pathnameToArgosName(pathname: string): string {
+  return pathname.replace(/^\/|\/$/g, "") || "index";
+}

website/docs/configuration/scanner/aws_ec2.md

@@ -1,5 +1,6 @@
 ---
-title: "AWS EC2"
+title: "Configure AWS EC2 Resource Scanner for TerediX"
+sidebar_label: AWS EC2
 ---
 
 # AWS EC2

website/docs/configuration/scanner/aws_ecr.md

@@ -1,5 +1,6 @@
 ---
-title: "AWS ECR"
+title: "Configure AWS ECR Resource Scanner for TerediX"
+sidebar_label: AWS ECR
 ---
 
 # AWS ECR

website/docs/configuration/scanner/aws_rds.md

@@ -1,5 +1,6 @@
 ---
-title: "AWS RDS"
+title: "Configure AWS RDS Resource Scanner for TerediX"
+sidebar_label: AWS RDS
 ---
 
 # AWS RDS

website/docs/configuration/scanner/aws_s3.md

@@ -1,5 +1,6 @@
 ---
-title: "AWS S3"
+title: "Configure AWS S3 Resource Scanner for TerediX"
+sidebar_label: AWS S3
 ---
 
 # AWS S3

website/docs/configuration/scanner/file_system.md

@@ -1,5 +1,6 @@
 ---
-title: "File System"
+title: "Configure File System Resource Scanner for TerediX"
+sidebar_label: File System
 ---
 
 # File System

website/docs/configuration/scanner/github_repository.md

@@ -1,5 +1,6 @@
 ---
-title: "GitHub Repository"
+title: "Configure GitHub Repository Resource Scanner for TerediX"
+sidebar_label: GitHub Repository
 ---
 
 # GitHub Repository

website/docs/configuration/scanner/overview.md

@@ -1,6 +1,7 @@
 ---
 sidebar_position: 1
-title: "Overview"
+title: "Available Scanners and Configurations"
+sidebar_label: Overview
 ---
 
 # Source

website/docs/contribution/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Contribution",
+  "position": 4,
+  "link": {
+    "type": "generated-index"
+  }
+}

website/docs/contribution/overview.md

@@ -0,0 +1,69 @@
+---
+sidebar_position: 1
+title: "Overview"
+---
+
+# Overview
+
+Contributing to TerediX is a great way to help the open source community. We appreciate contributions of all kinds, from code to documentation, from small tweaks to significant features. Here are some of the ways you can contribute:
+
+## Contribute to Codebase
+
+If you're looking to code, start by checking out our [issues](https://github.com/shaharia-lab/terediX/issues). Here's how you can contribute:
+
+
+- **Tackle Existing Issues**: Look for issues labeled **[good first issue](https://github.com/shaharia-lab/terediX/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)** or **[help wanted](https://github.com/shaharia-lab/terediX/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)** for ideas to start contributing.
+- **Submit Pull Requests**: If you have a fix or feature in mind, feel free to create an issue first to discuss it. After the idea is fleshed out, submit a pull request (PR) for review.
+- **Write Tests**: Help improve the project's reliability and coverage by writing tests.
+
+## Participate in Discussions
+
+Join the conversation on open issues:
+
+- **Provide Feedback**: Share your insights or propose new ideas.
+- **Answer Questions**: Help out others by answering questions you're knowledgeable about.
+- **Engage in Code Reviews**: Provide constructive feedback on open PRs.
+
+## Improve Documentation
+
+Good documentation is crucial for any project. Here's how you can help:
+
+- **Update Outdated Content**: Refresh any documentation that's out of date.
+- **Add Missing Pieces**: Contribute additional information where you see gaps.
+- **Enhance Readability**: Improve the structure or clarity of the documentation.
+
+Documentation updates can be submitted as PRs, just like code.
+
+## Support Through Sponsorship
+
+Your financial support can make a big difference:
+
+- **Sponsor the Project**: Contributions can help maintainers dedicate more time to the project. Check out our [sponsorship page](https://github.com/sponsors/shaharia-lab) for more details.
+
+## How to Get Started
+
+Ready to contribute? Here's how to get started:
+
+1. **Fork the Repository**: Create your own fork of TerediX.
+2. **Clone Your Fork**: Work locally on your own machine.
+3. **Create a Branch**: Always work on a new branch for your changes.
+4. **Commit Your Changes**: Write clear, concise commit messages.
+5. **Submit a Pull Request**: Push your changes to your fork and open a PR against the main TerediX repository.
+
+For more detailed instructions, check our [CONTRIBUTING.md](https://github.com/shaharia-lab/terediX/blob/master/CONTRIBUTING.md).
+
+## Stay Connected
+
+Stay up-to-date with the project:
+
+- **Follow on GitHub**: Watch the repository for new issues and updates.
+- **Join Our Community**: Participate in discussions, meetups, and events.
+
+Thank you for considering a contribution to TerediX. Your efforts are what keep the open source community vibrant and growing!
+
+---
+
+*This contributing guide is open to updates. Feel free to submit a PR to improve it!*
+
+
+Contributions are welcome! Please follow the guidelines outlined in the [CONTRIBUTING](https://github.com/shaharia-lab/terediX/blob/master/CONTRIBUTING.md) file.

website/docs/contribution/prepare-local-env.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 2
+title: "Prepare Local Environment"
+---
+
+We have made it easy to get started working on TerediX codebase. You can follow the steps below to get started.
+
+## Prerequisites
+- Docker
+
+## Clone the repository
+
+```bash
+git clone git@github.com:shaharia-lab/terediX.git
+cd terediX
+```
+
+## Run TerediX inside Docker
+
+We have a Docker image for development purpose. You can run the following command to start the development server.
+
+```bash
+docker run -i -d --name teredix-dev \
+  -v $(pwd):/home/app/src \
+  -p 3000:3000 \
+  -p 2112:2112 \
+  ghcr.io/shaharia-lab/teredix:dev
+```
+
+## Access the development environment
+
+You can access development environment in Docker container by running the following command:
+
+```bash
+docker exec -it teredix-dev bash
+```
+
+Then, you can go to the project root
+
+```bash
+su app
+cd ~/src/
+```
+
+## Test the development environment
+
+```bash
+make test-unit
+```
+
+## Run website
+
+```bash
+cd website
+yarn install
+yarn start --host=0.0.0.0 --port=3000
+```
+
+Now in your browser, you can access the website at http://localhost:3000
+
+Voila! You are ready to contribute to TerediX.

website/docusaurus.config.js

@@ -6,7 +6,7 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula');
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
-  title: 'terediX',
+  title: 'TerediX',
   tagline: 'Tech Resource Discovery - an open source initiative by Shaharia Lab OÜ',
   favicon: 'img/favicon.ico',
 

website/package.json

@@ -24,8 +24,12 @@
     "react-dom": "^17.0.2"
   },
   "devDependencies": {
+    "@argos-ci/cli": "^1.0.3",
+    "@argos-ci/playwright": "^1.3.0",
     "@docusaurus/module-type-aliases": "^2.4.3",
+    "@playwright/test": "^1.40.0",
     "@tsconfig/docusaurus": "^2.0.2",
+    "cheerio": "^1.0.0-rc.12",
     "typescript": "^4.7.4"
   },
   "browserslist": {

website/playwright.config.ts

@@ -0,0 +1,19 @@
+import {devices} from '@playwright/test';
+import type {PlaywrightTestConfig} from '@playwright/test';
+
+const config: PlaywrightTestConfig = {
+    webServer: {
+        port: 3000,
+        command: 'yarn docusaurus serve',
+    },
+    projects: [
+        {
+            name: 'chromium',
+            use: {
+                ...devices['Desktop Chrome'],
+            },
+        },
+    ],
+};
+
+export default config;

website/screenshot.css

@@ -0,0 +1,35 @@
+/*
+We need to hide some elements in Argos/Playwright screenshots
+Those elements are source of flakiness due to nondeterministic rendering
+They don't consistently render exactly the same across CI runs
+ */
+
+/******* DOCUSAURUS GLOBAL / THEME *******/
+
+/* Iframes can load lazily */
+iframe,
+/* Avatar images can be flaky due to using external sources: GitHub/Unavatar */
+.avatar__photo,
+/* Gifs load lazily and are animated */
+img[src$='.gif'],
+/* Algolia Keyboard shortcuts appear with a little delay */
+.DocSearch-Button-Keys > kbd,
+/* The live playground preview can often display dates/counters */
+[class*='playgroundPreview'] {
+  visibility: hidden;
+}
+
+/*
+Different docs last-update dates can alter layout
+"visibility: hidden" is not enough
+ */
+.theme-last-updated {
+  display: none;
+}
+
+/*
+Mermaid diagrams are rendered client-side and produce layout shifts
+ */
+.docusaurus-mermaid-container {
+  display: none;
+}

website/screenshot.spec.ts

@@ -0,0 +1,33 @@
+import * as fs from "fs";
+import { test } from "@playwright/test";
+import { argosScreenshot } from "@argos-ci/playwright";
+import { extractSitemapPathnames, pathnameToArgosName } from "argos/utils";
+
+// Constants:
+const siteUrl = "http://localhost:3000";
+const sitemapPath = "./build/sitemap.xml";
+const stylesheetPath = "./screenshot.css";
+const stylesheet = fs.readFileSync(stylesheetPath).toString();
+
+// Wait for hydration, requires Docusaurus v2.4.3+
+// See https://github.com/facebook/docusaurus/pull/9256
+// Docusaurus adds a <html data-has-hydrated="true"> once hydrated
+function waitForDocusaurusHydration() {
+  return document.documentElement.dataset.hasHydrated === "true";
+}
+
+function screenshotPathname(pathname: string) {
+  test(`pathname ${pathname}`, async ({ page }) => {
+    const url = siteUrl + pathname;
+    await page.goto(url);
+    await page.waitForFunction(waitForDocusaurusHydration);
+    await page.addStyleTag({ content: stylesheet });
+    await argosScreenshot(page, pathnameToArgosName(pathname));
+  });
+}
+
+test.describe("Docusaurus site screenshots", () => {
+  const pathnames = extractSitemapPathnames(sitemapPath);
+  console.log("Pathnames to screenshot:", pathnames);
+  pathnames.forEach(screenshotPathname);
+});