chore(docs): Add docs about architecture and fix structure

[kamilprz]

Description

The main goal of this PR was to document the Retina architecture, namely the data plane and the available control planes. While working on this, I also made some smaller changes to improve our consistency.

What this PR does:

Smaller changes

• Change the favicon image being used to one with a better aspect ratio. See below for screenshots of before/after.
  • The current logo looks stretched in browser tabs and bookmarks due to the aspect ratio and not enough negative space.
• Restructure the way our headings and pages are organised. (This meant a number of files had to be renamed/moved, whose content was not touched.)
  • For example currently if you click on "Captures" you navigate to a landing page/readme, but if you click on "Installation" it opens up a drop down of its pages. This is inconsistent. This PR makes all of the headings open up by default. See screenshots below for before/after.
• Added subheadings to contributing page to make it easier to read.

Architecture docs

• A new "Architecture" page is added to the newly introduced "Introduction" heading. This discusses the Data Plane and the available Control Planes.
  • As part of this a number of diagrams are introduced. Both the .png and the source for the diagram .excalidraw are included so that the diagrams can be versioned.
• Update the "What is Retina?" page to be consistent with the landing page of retina.sh in terms of the feature descriptions. Also added a "What is Hubble?" subsection with a brief description.

Related Issue

#1055

There is also another PR opened for Hubble installation - #1223

Checklist

• I have read the contributing documentation.
• I signed and signed-off the commits (git commit -S -s ...). See this documentation on signing commits.
• I have correctly attributed the author(s) of the code.
• I have tested the changes locally.
• I have followed the project's style guidelines.
• I have updated the documentation, if necessary.
• I have added tests, if applicable.

Screenshots (if applicable) or Testing Completed

I think its a bit redundant to put the Architecture Diagrams in here, as the files themselves are included. So check those out directly. Or open up a preview of the markdown page itself in GitHub.

Retina favicon image

Example of new file structure - showcasing that the heading now opens rather than having a landing page when clicked on.

Parity of feature highlight between retina.sh and "What is Retina?" page.

---

Please refer to the CONTRIBUTING.md file for more information on how to contribute to this project.

[kamilprz]

Able to run make docs-prod and serve the page from /site.

Build

~/src/retina git:architecture-docs
> make docs-prod
docker run -i -p 3000:3000 -v /home/kamilp/src/retina:/retina -w /retina/ node:20-alpine npm install --prefix site && npm run build --prefix site

up to date, audited 1339 packages in 2s

347 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
npm notice
npm notice New major version of npm available! 10.8.2 -> 11.0.0
npm notice Changelog: https://github.com/npm/cli/releases/tag/v11.0.0
npm notice To update run: npm install -g [email protected]
npm notice

> [email protected] build
> docusaurus build


   ------------------------------------------------------------------------------------------------------------------------------------------------------

                                                               Update available 3.6.1 → 3.7.0
                                                                                 .....

   ------------------------------------------------------------------------------------------------------------------------------------------------------

[INFO] [en] Creating an optimized production build...


✔ Client
  Compiled successfully in 20.53s

✔ Server


<w> [webpack.cache.PackFileCacheStrategy] Caching failed for pack: Error: EACCES: permission denied, mkdir '/home/kamilp/src/retina/site/node_modules/.cache/webpack/server-production-en'

● Client █████████████████████████ cache (99%) shutdown IdleFileCachePlugin
 serialize pack

✔ Server


<w> [webpack.cache.PackFileCacheStrategy] Caching failed for pack: Error: EACCES: permission denied, mkdir '/home/kamilp/src/retina/site/node_modules/.cache/webpack/client-production-en'
docusaurus-lunr-search:: Building search docs and lunr index file
docusaurus-lunr-search:: Start scanning documents in 2 threads
docusaurus-lunr-search:: Indexing time: 624.868ms
docusaurus-lunr-search:: indexed 38 documents out of 38
docusaurus-lunr-search:: writing search-doc.json
docusaurus-lunr-search:: writing search-doc-1737036699828.json
docusaurus-lunr-search:: writing lunr-index.json
docusaurus-lunr-search:: writing lunr-index-1737036699828.json
docusaurus-lunr-search:: End of process
[SUCCESS] Generated static files in "build".
[INFO] Use `npm run serve` command to test your build locally.
                                                                                                                                                     30.959s

Serve

~/src/retina git:architecture-docs
> cd site
~/src/retina/site git:architecture-docs
> npm run serve

> [email protected] serve
> docusaurus serve


   ------------------------------------------------------------------------------------------------------------------------------------------------------

                                                               Update available 3.6.1 → 3.7.0
                                                                                 .....

   ------------------------------------------------------------------------------------------------------------------------------------------------------

[SUCCESS] Serving "build" directory at: http://localhost:3000/

[anubhabMajumdar]

Adding the watcher information here makes it confusing. Describe it in a later paragraph. Also, mention why watchers are required.

[kamilprz]

cb835a6 I moved the watchers to a new paragraph and added some new detail. Please correct me if I am wrong. Admittedly I'm not super familiar with the watchers :)

[nddq]

this image doesn't load correctly, might be because of the space in the image's name might messing up the path or it's a Github issue