From 68f3340e4c10260821110ce602f979108e6b34f7 Mon Sep 17 00:00:00 2001 From: Joao Eduardo Luis Date: Sun, 24 Mar 2024 11:30:36 +0000 Subject: [PATCH] docs: adjust for new doc website Signed-off-by: Joao Eduardo Luis --- docs/contributing.md | 3 - .../0000-use-markdown-any-decision-records.md | 4 +- docs/decisions/0010-sfs-versioning.md | 2 +- docs/decisions/0011-sfs-timestamps.md | 2 +- docs/decisions/0019-severity-labels.md | 5 +- docs/decisions/README.md | 9 ++- docs/decisions/adr-template.md | 71 ++++++++++--------- docs/{ => guide}/advanced-usage.md | 0 docs/{ => guide}/config-s3gw.md | 0 docs/guide/contributing.md | 3 + docs/{ => guide}/developing.md | 0 docs/{ => guide}/helm-charts.md | 0 docs/{index.md => guide/introduction.md} | 28 ++++---- docs/{ => guide}/license.md | 2 +- docs/{ => guide}/metrics.md | 0 docs/{ => guide}/quickstart.md | 3 +- docs/{ => guide}/roadmap.md | 0 docs/{ => guide}/s3-compatibility-table.md | 0 docs/guide/s3gw-repos.md | 9 +++ docs/{ => guide}/s3gw-with-k3s.md | 0 docs/{ => guide}/s3gw-with-k8s.md | 0 docs/{ => guide}/testing.md | 0 docs/{ => guide}/troubleshoot-s3gw.md | 0 docs/{ => guide}/ui.md | 0 docs/ideas/PID-0-reserved.md | 2 +- docs/readme.md | 64 ----------------- docs/research/ha/RATIONALE.md | 32 ++++----- docs/s3gw-repos.md | 9 --- 28 files changed, 97 insertions(+), 151 deletions(-) delete mode 100644 docs/contributing.md rename docs/{ => guide}/advanced-usage.md (100%) rename docs/{ => guide}/config-s3gw.md (100%) create mode 100644 docs/guide/contributing.md rename docs/{ => guide}/developing.md (100%) rename docs/{ => guide}/helm-charts.md (100%) rename docs/{index.md => guide/introduction.md} (91%) rename docs/{ => guide}/license.md (91%) rename docs/{ => guide}/metrics.md (100%) rename docs/{ => guide}/quickstart.md (88%) rename docs/{ => guide}/roadmap.md (100%) rename docs/{ => guide}/s3-compatibility-table.md (100%) create mode 100644 docs/guide/s3gw-repos.md rename docs/{ => guide}/s3gw-with-k3s.md (100%) rename docs/{ => guide}/s3gw-with-k8s.md (100%) rename docs/{ => guide}/testing.md (100%) rename docs/{ => guide}/troubleshoot-s3gw.md (100%) rename docs/{ => guide}/ui.md (100%) delete mode 100644 docs/readme.md delete mode 100644 docs/s3gw-repos.md diff --git a/docs/contributing.md b/docs/contributing.md deleted file mode 100644 index a6e5354d..00000000 --- a/docs/contributing.md +++ /dev/null @@ -1,3 +0,0 @@ - - -{{ external_markdown('https://raw.githubusercontent.com/s3gw-tech/s3gw/main/CONTRIBUTING.md', '') }} diff --git a/docs/decisions/0000-use-markdown-any-decision-records.md b/docs/decisions/0000-use-markdown-any-decision-records.md index 7bc460be..cf910076 100644 --- a/docs/decisions/0000-use-markdown-any-decision-records.md +++ b/docs/decisions/0000-use-markdown-any-decision-records.md @@ -17,12 +17,12 @@ Where should the records live? ### Location -- +- [s3gw repository](https://github.com/s3gw-tech/s3gw) - SUSE Confluence ## Decision Outcome -MADR in aquarist-labs/s3gw, because +MADR in s3gw-tech/s3gw, because - Architecture, design and code decisions should be open and public - Github merge request workflow adds an easy review workflow we diff --git a/docs/decisions/0010-sfs-versioning.md b/docs/decisions/0010-sfs-versioning.md index d64ba20c..5bff9519 100644 --- a/docs/decisions/0010-sfs-versioning.md +++ b/docs/decisions/0010-sfs-versioning.md @@ -8,7 +8,7 @@ In this document we only look at tables Objects and Versioned Objects. An *object* has a name, id, and reference to a *bucket* -A *object version* has an id, checksum, {create, commit, delete}_time, +A *object version* has an id, checksum, \{create, commit, delete\}_time, mtime, size, **state**, **type**, ETag, serialized attributes, etc. An *object* is a group of versions identified by bucket and name. diff --git a/docs/decisions/0011-sfs-timestamps.md b/docs/decisions/0011-sfs-timestamps.md index 2a31c5dc..9f39fc9f 100644 --- a/docs/decisions/0011-sfs-timestamps.md +++ b/docs/decisions/0011-sfs-timestamps.md @@ -1,5 +1,5 @@ - # SFS Timestamps + ## Context and Problem Statement diff --git a/docs/decisions/0019-severity-labels.md b/docs/decisions/0019-severity-labels.md index 174dd4a8..da358a2b 100644 --- a/docs/decisions/0019-severity-labels.md +++ b/docs/decisions/0019-severity-labels.md @@ -39,7 +39,7 @@ issues should have a severity label set from now on. ### Longhorn -This is the current severity labels used by : +This is the current severity labels used by [Longhorn](https://github.com/longhorn/longhorn/labels): - severity/1 - Function broken (a critical incident with very high impact (ex: data corruption, failed upgrade) @@ -52,8 +52,7 @@ This is the current severity labels used by +This is the current severity fields used for [openSUSE bugs](https://en.opensuse.org/openSUSE:Bug_definitions): - Blocker - Prevents developers or testers from performing their jobs. Impacts the development process diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 71aaf365..b4b402a5 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -1,3 +1,8 @@ +--- +title: Introduction +--- + + # Decisions This directory contains decision records for s3gw. @@ -10,5 +15,5 @@ This directory contains decision records for s3gw. ## Resources -- MADRs . -- General information about ADRs . +- [MADRs](https://adr.github.io/madr/) +- [General information about ADRs](https://adr.github.io/) diff --git a/docs/decisions/adr-template.md b/docs/decisions/adr-template.md index ea8fd0b0..9a089150 100644 --- a/docs/decisions/adr-template.md +++ b/docs/decisions/adr-template.md @@ -1,96 +1,99 @@ --- +title: Template + # These are optional elements. Feel free to remove any of them. -status: {proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)} -date: {YYYY-MM-DD when the decision was last updated} -deciders: {list everyone involved in the decision} -consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication} -informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication} +status: "proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)" +date: "YYYY-MM-DD when the decision was last updated" +deciders: "list everyone involved in the decision" +consulted: "list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication" +informed: "list everyone who is kept up-to-date on progress; and with whom there is a one-way communication" --- -# {short title of solved problem and solution} + +# short title of solved problem and solution ## Context and Problem Statement -{Describe the context and problem statement, e.g., in free form using two to +Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question and add links to collaboration -boards or issue management systems.} +boards or issue management systems. ## Decision Drivers -- {decision driver 1, e.g., a force, facing concern, …} -- {decision driver 2, e.g., a force, facing concern, …} +- decision driver 1, e.g., a force, facing concern, … +- decision driver 2, e.g., a force, facing concern, … - … ## Considered Options -- {title of option 1} -- {title of option 2} -- {title of option 3} +- title of option 1 +- title of option 2 +- title of option 3 - … ## Decision Outcome -Chosen option: "{title of option 1}", because {justification. e.g., only option, -which meets k.o. criterion decision driver | which resolves force {force} | … | -comes out best (see below)}. +Chosen option: "title of option 1", because "justification. e.g., only option, +which meets k.o. criterion decision driver | which resolves force 'force' | … | +comes out best (see below)". ### Positive Consequences -- {e.g., improvement of one or more desired qualities, …} +- e.g., improvement of one or more desired qualities, … - … ### Negative Consequences -- {e.g., compromising one or more desired qualities, …} +- e.g., compromising one or more desired qualities, … - … ## Validation -{describe how the implementation of/compliance with the ADR is validated. E.g., -by a review or an ArchUnit test} +describe how the implementation of/compliance with the ADR is validated. E.g., +by a review or an ArchUnit test ## Pros and Cons of the Options -### {title of option 1} +### title of option 1 -{example | description | pointer to more information | …} +example | description | pointer to more information | … -- Good, because {argument a} -- Good, because {argument b} +- Good, because "argument a" +- Good, because "argument b" -- Neutral, because {argument c} -- Bad, because {argument d} +- Neutral, because "argument c" +- Bad, because "argument d" - … -### {title of other option} +### title of other option -{example | description | pointer to more information | …} +example | description | pointer to more information | … -- Good, because {argument a} -- Good, because {argument b} -- Neutral, because {argument c} -- Bad, because {argument d} +- Good, because "argument a" +- Good, because "argument b" +- Neutral, because "argument c" +- Bad, because "argument d" - … ## More Information -{You might want to provide additional evidence/confidence for the decision +You might want to provide additional evidence/confidence for the decision outcome here and/or document the team agreement on the decision and/or define when this decision when and how the decision should be realized and if/when it should be re-visited and/or how the decision is validated. Links to other -decisions and resources might here appear as well.} +decisions and resources might here appear as well. diff --git a/docs/advanced-usage.md b/docs/guide/advanced-usage.md similarity index 100% rename from docs/advanced-usage.md rename to docs/guide/advanced-usage.md diff --git a/docs/config-s3gw.md b/docs/guide/config-s3gw.md similarity index 100% rename from docs/config-s3gw.md rename to docs/guide/config-s3gw.md diff --git a/docs/guide/contributing.md b/docs/guide/contributing.md new file mode 100644 index 00000000..c092e5b5 --- /dev/null +++ b/docs/guide/contributing.md @@ -0,0 +1,3 @@ + + + diff --git a/docs/developing.md b/docs/guide/developing.md similarity index 100% rename from docs/developing.md rename to docs/guide/developing.md diff --git a/docs/helm-charts.md b/docs/guide/helm-charts.md similarity index 100% rename from docs/helm-charts.md rename to docs/guide/helm-charts.md diff --git a/docs/index.md b/docs/guide/introduction.md similarity index 91% rename from docs/index.md rename to docs/guide/introduction.md index a7fb1619..8491d04f 100644 --- a/docs/index.md +++ b/docs/guide/introduction.md @@ -1,25 +1,21 @@ -# Welcome to the s3gw project - -## About the project - -The s3gw project is split into 4 work streams: [rgw/sfs-ceph][1] (backend), -[s3gw][2] (tooling), [s3gw-charts][3] (helm charts) and [s3gw-ui][4] -(frontend). +--- +slug: / +--- -## Project vision +# Welcome to the s3gw project -### What are we doing? +## What are we doing? The s3gw project helps Kubernetes users who need object storage (S3) to back up their application data to a ([Longhorn][5]) PV by offering a lightweight, Open Source S3 service, which is easy to deploy in a Cloud Native world. -### Why are we doing it? +## Why are we doing it? We have identified a need for making cluster data backups easily available for apps that do not require petabyte-scale storage. -### Features +## Features - An intuitive UI - S3 API compatibility @@ -27,7 +23,7 @@ apps that do not require petabyte-scale storage. - Leverages the feature-rich S3 gateway from Ceph - Strong integration with the Rancher Portfolio -### Use cases +## Use cases - Epinio: Backups/CRDs - Harvester: Backups @@ -35,7 +31,7 @@ apps that do not require petabyte-scale storage. - K3S/Edge - SAP Data Intelligence -### Value proposition +## Value proposition - Ideal for small-scale deployments/Edge - Lightweight, simple User Experience @@ -43,6 +39,12 @@ apps that do not require petabyte-scale storage. - Designed to integrate with Rancher's product catalog - Open source licensing (Apache 2.0) +## About the project + +The s3gw project is split into 4 work streams: [rgw/sfs-ceph][1] (backend), +[s3gw][2] (tooling), [s3gw-charts][3] (helm charts) and [s3gw-ui][4] +(frontend). + [1]: https://github.com/s3gw-tech/s3gw-ceph [2]: https://github.com/s3gw-tech/s3gw [3]: https://github.com/s3gw-tech/s3gw-charts diff --git a/docs/license.md b/docs/guide/license.md similarity index 91% rename from docs/license.md rename to docs/guide/license.md index 166a762a..4a4fd47e 100644 --- a/docs/license.md +++ b/docs/guide/license.md @@ -4,7 +4,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use licensed files except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 or the LICENSE file in this repository. diff --git a/docs/metrics.md b/docs/guide/metrics.md similarity index 100% rename from docs/metrics.md rename to docs/guide/metrics.md diff --git a/docs/quickstart.md b/docs/guide/quickstart.md similarity index 88% rename from docs/quickstart.md rename to docs/guide/quickstart.md index 118b10ae..37ab18d1 100644 --- a/docs/quickstart.md +++ b/docs/guide/quickstart.md @@ -6,7 +6,8 @@ You can install the s3gw via the Rancher App Catalog. The steps are as follows: - Cluster -> Projects/Namespaces - create the `s3gw` namespace. - Apps -> Repositories -> Create `s3gw` using the s3gw-charts Web URL - and the main branch. + [https://s3gw-tech.github.io/s3gw-charts/](https://s3gw-tech.github.io/s3gw-charts/) + and the main branch. - Apps -> Charts -> Install Traefik. - Apps -> Charts -> Install `s3gw`. Select the `s3gw` namespace previously created. diff --git a/docs/roadmap.md b/docs/guide/roadmap.md similarity index 100% rename from docs/roadmap.md rename to docs/guide/roadmap.md diff --git a/docs/s3-compatibility-table.md b/docs/guide/s3-compatibility-table.md similarity index 100% rename from docs/s3-compatibility-table.md rename to docs/guide/s3-compatibility-table.md diff --git a/docs/guide/s3gw-repos.md b/docs/guide/s3gw-repos.md new file mode 100644 index 00000000..bdf627c5 --- /dev/null +++ b/docs/guide/s3gw-repos.md @@ -0,0 +1,9 @@ +# S3GW Repositories + +The S3 Gateway includes the following projects: + +- [s3gw-tech/s3gw](https://github.com/s3gw-tech/s3gw) +- [s3gw-tech/s3gw-ceph](https://github.com/s3gw-tech/s3gw-ceph) +- [s3gw-tech/s3gw-charts](https://github.com/s3gw-tech/s3gw-charts) +- [s3gw-tech/s3gw-status](https://github.com/s3gw-tech/s3gw-status) +- [s3gw-tech/s3gw-cosi-driver](https://github.com/s3gw-tech/s3gw-cosi-driver) diff --git a/docs/s3gw-with-k3s.md b/docs/guide/s3gw-with-k3s.md similarity index 100% rename from docs/s3gw-with-k3s.md rename to docs/guide/s3gw-with-k3s.md diff --git a/docs/s3gw-with-k8s.md b/docs/guide/s3gw-with-k8s.md similarity index 100% rename from docs/s3gw-with-k8s.md rename to docs/guide/s3gw-with-k8s.md diff --git a/docs/testing.md b/docs/guide/testing.md similarity index 100% rename from docs/testing.md rename to docs/guide/testing.md diff --git a/docs/troubleshoot-s3gw.md b/docs/guide/troubleshoot-s3gw.md similarity index 100% rename from docs/troubleshoot-s3gw.md rename to docs/guide/troubleshoot-s3gw.md diff --git a/docs/ui.md b/docs/guide/ui.md similarity index 100% rename from docs/ui.md rename to docs/guide/ui.md diff --git a/docs/ideas/PID-0-reserved.md b/docs/ideas/PID-0-reserved.md index b2c3e3e2..b59f5002 100644 --- a/docs/ideas/PID-0-reserved.md +++ b/docs/ideas/PID-0-reserved.md @@ -1,6 +1,6 @@ --- status: accepted -tags: area/docs +tags: [ area/docs ] updated: 20231013 --- diff --git a/docs/readme.md b/docs/readme.md deleted file mode 100644 index 16800dea..00000000 --- a/docs/readme.md +++ /dev/null @@ -1,64 +0,0 @@ -# s3gw Documentation - -[![Documentation Status](https://readthedocs.org/projects/example-mkdocs-basic/badge/?version=latest)](https://s3gw-docs.readthedocs.io/en/latest/?badge=latest) - -The documentation for the s3gw project is generated by -[Mkdocs](https://github.com/mkdocs/mkdocs), which is a project documentation -generator using Markdown. - -It is hosted in [Read The Docs](https://readthedocs.org/) which takes care of -building, versioning, and hosting the documentation. - -The generated documentation for this project can be found -[here](https://s3gw-docs.readthedocs.io/en/latest/). - -## Getting started - -If you are using Read the Docs for the first time, have a look at the official -[Read the Docs Tutorial](https://docs.readthedocs.io/en/stable/tutorial/index.html). - -This is how our documentation is currently structured: - -- [docs/](https://github.com/s3gw-tech/s3gw/tree/main/docs) - A basic MkDocs project lives in `docs/`, it was generated using MkDocs defaults. - All the `*.md` make up sections in the documentation. - -- [.readthedocs.yaml](https://github.com/s3gw-tech/s3gw/tree/main/.readthedocs.yaml) - Read the Docs Build configuration is stored in `.readthedocs.yaml`. - -- [mkdocs.yml](https://github.com/s3gw-tech/s3gw/tree/main/mkdocs.yaml) - A [MkDocs configuration](https://www.mkdocs.org/user-guide/configuration/) is - stored here, including the navigation structure, a few extensions for MkDocs - and Markdown. Add your own configurations here, such as extensions and themes. - Remember that many extensions and themes require additional Python packages to - be installed. - -- [docs/requirements.txt](https://github.com/s3gw-tech/s3gw/tree/main/docs/requirements.txt) - and -- [docs/requirements.in](https://github.com/s3gw-tech/s3gw/tree/main/docs/requirements.in) - Python dependencies are - [pinned](https://docs.readthedocs.io/en/latest/guides/reproducible-builds.html) - (uses [pip-tools](https://pip-tools.readthedocs.io/en/latest/)) here. Make - sure to add your Python dependencies to `requirements.txt` or if you choose - [pip-tools](https://pip-tools.readthedocs.io/en/latest/), edit - `docs/requirements.in` and remember to run to run - `pip-compile docs/requirements.in`. - -## Run Mkdocs locally - -This project has a standard MkDocs layout which is built by Read the Docs almost -the same way that you would build it locally. - -You can build and view this documentation project locally - we recommend that -you activate -[a local Python virtual environment first](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment): - -```console -# Install required Python dependencies (MkDocs etc.) -pip install -r docs/requirements.txt - -# Run the mkdocs development server -mkdocs serve -``` - -That's it! You're now able to run the s3gw project documentation locally. diff --git a/docs/research/ha/RATIONALE.md b/docs/research/ha/RATIONALE.md index b98f2e4e..89f83702 100644 --- a/docs/research/ha/RATIONALE.md +++ b/docs/research/ha/RATIONALE.md @@ -504,9 +504,9 @@ The file name, normally, contains some information such as: - #measures: `100` -||| +||| |---|---| -|| | +|| | ### segfault_localhost_zeroload_emptydb @@ -517,9 +517,9 @@ The file name, normally, contains some information such as: - #measures: `100` -||| +||| |---|---| -|| | +|| | ### regular_localhost_load_fio_64_write @@ -550,9 +550,9 @@ bs=1m ``` -||| +||| |---|---| -|| | +|| | ### regular_localhost_zeroload_400_800Kdb @@ -565,9 +565,9 @@ bs=1m - #measures: `100` -||| +||| |---|---| -|| | +|| | #### 800K objects - measures done with the WAL file still to be processed (size 32G) @@ -578,9 +578,9 @@ bs=1m - #measures: `100` -||| +||| |---|---| -|| | +|| | ### regular-localhost-incremental-fill-5k @@ -594,9 +594,9 @@ Between every restart there is an interposed `PUT-Object` sequence, each of 5K o the sqlite db initially contained 800K objects. -||| +||| |---|---| -|| | +|| | ### scale_deployment_0_1-k3s3nodes_zeroload_emptydb @@ -618,9 +618,9 @@ The schema is the following: 6. trigger 100 pod restarts -||| +||| |---|---| -|| | +|| | ## Tested Scenarios - S3-workload during s3gw Pod outage @@ -655,7 +655,7 @@ For each scenario tested we produce a specific artifact: - #S3-operations: `394` -||| +||| |---|---| @@ -669,7 +669,7 @@ For each scenario tested we produce a specific artifact: - #S3-operations: `504` -||| +||| |---|---| diff --git a/docs/s3gw-repos.md b/docs/s3gw-repos.md deleted file mode 100644 index cb37c812..00000000 --- a/docs/s3gw-repos.md +++ /dev/null @@ -1,9 +0,0 @@ -# S3GW Repositories - -The S3 Gateway includes the following projects: - -- s3gw-tech/s3gw -- s3gw-tech/s3gw-ceph -- s3gw-tech/s3gw-charts -- s3gw-tech/s3gw-status -- s3gw-tech/s3gw-cosi-driver