ninja: small doc cleanup

Author: agilelab-tmnd1991

README.md

@@ -3,10 +3,8 @@
 Fork of Delta-Sharing with the following goals:
 
 - allow to share data in different table formats (iceberg, hudi, hive-style) leveraging the delta-sharing protocol and adding new APIs where needed
-- whitefox protocol will cover not only data-sharing needs but also administration needs, such as the creation of 
- shares, configuration of sources, etc.
-- provide a production-grade server implementation of both the original delta-sharing protocol and the new whitefox 
- protocol
+- whitefox protocol will cover not only data-sharing needs but also administration needs, such as the creation of shares, configuration of sources, etc.
+- provide a production-grade server implementation of both the original delta-sharing protocol and the new whitefox protocol
 
 This repository contains:
 
@@ -17,17 +15,16 @@ This repository contains:
 
 # Protocols
 
-Whitefox protocol is rendered [here](https://agile-lab-dev.github.io/whitefox/openapi_whitefox.html)
-
-The original delta-sharing protocol is rendered [here](https://agile-lab-dev.github.io/whitefox/openapi_delta-sharing.html)
-
+See the documentation site [here](https://agile-lab-dev.github.io/whitefox/)
 
 # Reporting Issues
 
 We use [GitHub Issues](https://github.com/agile-lab-dev/whitefox/issues) to track community-reported issues. You can also [contact Agile Lab](mailto:communityimpact@agilelab.it) for getting answers.
 
 # Contributing 
+
 We welcome contributions to Whitefox. See our [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
 
 # License
+
 [Apache License 2.0](LICENSE.txt).

docsite/docs/architecture/HighLevelDesign.md

@@ -0,0 +1,7 @@
+---
+toc_min_heading_level: 2
+toc_max_heading_level: 5
+---
+# Architecture
+
+Unders this section architectural design decisions are collected.

docsite/docs/architecture/README.md

@@ -1,10 +1,4 @@
-# Whitefox protocol
-
-To qualify all the APIs as:
-- **supported**
-- **minor change**
-- **breaking change**
-
+# Whitefox logical organization
 
 ## Concepts:
 
@@ -25,39 +19,3 @@ Internally organization is a bit more complex:
 - Provider: a composed entity that allows to access a table existing in an external system. A provider is composed by a storage system and optionally a metastore (or catalog?)
 - Storage: an object storage that contains the table data
 - Metastore: a system that provides metadata about tables, it is mandatory for Iceberg tables and can be useful for discovery in general
-
-## Users
-
-Initially we define two kind of users:
-
-1. admins
-2. guests
-
-Admins can:
-
-- create/update/delete storages
-- create/update/delete metastores
-- create/update/delete providers
-- create/update/delete shares
-- create/update/delete schemas
-- create/update/delete tables
-- add guests as recipients of shares
-
-## STORAGES
-
-## METASTORES
-
-## PROVIDERS
-
-
-## SHARES
-- (from delta sharing [API page](https://github.com/agile-lab-dev/whitefox/blob/main/PROTOCOL.md) )
-
-## SCHEMAs/TABLEs
-- (from delta sharing [API page](https://github.com/agile-lab-dev/whitefox/blob/main/PROTOCOL.md))
-
-## ACCESS CONTROL
-- (from Databricks [documentation page](https://docs.databricks.com/api/workspace/shares/get) )
-
-## DATA ACCESS
-- (from delta sharing [API page](https://github.com/agile-lab-dev/whitefox/blob/main/PROTOCOL.md))

docsite/docs/protocols/whitefox-protocol.md renamed to docsite/docs/architecture/logical_organization.md

@@ -0,0 +1,9 @@
+# Memo 001
+
+## Strategic decisions:
+
+- Client libs coupling: we don’t want to embed into our lib the ones related to the support table and file formats.
+- Our clients will have a soft dependency, the users will need to couple their own Iceberg/Hudi/Delta libs and load in their runtime
+- The versions used for writing is included in the metadata, we assume the clients will always be able to read with libs version x everything written with versions <= x.
+- The server will load its own dependencies (ideally latest iceberg/delta/hudi standalone libraries)
+- Follow a cloud-native and decoupled approach for infrastructural dependencies (e.g. the underlying DB to host metadata shouldn't be a hard dependency, users should be able to plug the DB of their choice as long as it provides the APIs we need)

docsite/docs/architecture/memos/001_Memo.md

@@ -0,0 +1,5 @@
+{
+ "label": "Memos",
+ "collapsible": true,
+ "collapsed": false
+}

docsite/docs/architecture/memos/_category_.json

@@ -2,6 +2,18 @@
 sidebar_position: 1
 ---
 
-# Docs
+# Introduction
 
-Navigate on the left sidebar around documentation.
+Whitefox is a fork of Delta-Sharing with the following goals:
+
+- allow to share data in different table formats (iceberg, hudi, hive-style) leveraging the delta-sharing protocol and adding new APIs where needed
+- whitefox protocol will cover not only data-sharing needs but also administration needs, such as the creation of 
+ shares, configuration of sources, etc.
+- provide a production-grade server implementation of both the original delta-sharing protocol and the new whitefox 
+ protocol
+
+The [protocols](./protocols) page contains the original delta-sharing protocol and whitefox protocol.
+
+[Development Guidelines](./development_guidelines.md) contains relevant info to whoever wants to contribute to Whitefox and get started.
+
+[Architecture](./architecture) contains architectural design decisions.

docsite/docs/intro.md

@@ -5,6 +5,5 @@ sidebar_position: 1
 # Protocols
 
 - [Whitefox OpenApi](pathname:///openapi_whitefox.html)
-- [Whitefox protocol description](protocols/whitefox-protocol)
 - [Delta Sharing OpenApi](pathname:///openapi_delta-sharing.html)
 - [Delta Sharing protocol description](protocols/delta-sharing-protocol)

docsite/docs/protocols/README.md

@@ -4,6 +4,8 @@ toc_max_heading_level: 5
 ---
 # Delta Sharing Protocol
 
+See rendered OpenApi [here](pathname:///openapi_delta-sharing.html).
+
 # Overview
 
 [Delta Sharing](https://delta.io/sharing) is an open protocol for secure real-time exchange of large datasets, which enables secure data sharing across products for the first time. It is a simple REST protocol that securely shares access to part of a cloud dataset. It leverages modern cloud storage systems, such as S3, ADLS, or GCS, to reliably transfer large datasets.