docs: new structure and landing page

.gitattributes

@@ -5,5 +5,5 @@ docs/advanced_examples/data/** filter=lfs diff=lfs merge=lfs -text
 *.tar filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
 use_case_examples/cifar_10_with_model_splitting/mlir.txt filter=lfs diff=lfs merge=lfs -text
-docs/developer-guide/api/** binary
+docs/references/api/** binary
 use_case_examples/credit_scoring/hmeq.csv filter=lfs diff=lfs merge=lfs -text

.github/workflows/continuous-integration.yaml

@@ -520,7 +520,7 @@ jobs:
               - '!.*/**'
               - '!docs/_*/**'
               - '!docs/SUMMARY.md'
-              - '!docs/developer-guide/api/**.md'
+              - '!docs/references/api/**.md'
             dependencies:
               - deps_licenses/licenses_linux_user.txt.md5
             conftest:

.github/workflows/release.yaml

@@ -16,7 +16,7 @@ on:
       - 'release/*'
     paths:
       - src/concrete/ml/version.py
-      - 'docs/developer-guide/api/**'
+      - 'docs/references/api/**'
 
 # We need to make sure that the concurrency group is not identical to the continuous-integration.yaml
 # one, else the release workflow will be canceled when calling that latter for tests. More 

.gitignore

@@ -78,7 +78,7 @@ docs/_build/
 docs-copy/
 
 # GitBook
-docs/developer-guide/api/.pages
+docs/references/api/.pages
 
 # PyBuilder
 target/

Makefile

@@ -13,7 +13,7 @@ COUNT?=1
 RANDOMLY_SEED?=$$RANDOM
 PYTEST_OPTIONS:=
 POETRY_VERSION:=1.7.1
-APIDOCS_OUTPUT?="./docs/developer-guide/api"
+APIDOCS_OUTPUT?="./docs/references/api"
 OPEN_PR="true"
 
 # Force the installation of a Concrete Python version, which is very useful with nightly versions
@@ -425,10 +425,12 @@ docs_no_links: clean_docs check_docs_dollars
 	! grep -r "hint style" docs-copy
 	@# Replace $$, $/$ and /$$ by $
 	./script/make_utils/fix_double_dollars_issues_with_mdformat.sh docs-copy --single_dollar
+	@# Replace `href="*.md` patterns with `href="*.html` because Sphinx does not handle them
+	./script/make_utils/fix_md_to_html_conversion_from_sphinx_in_href.sh docs-copy
+	@# Replace `references/api/README.md` with `_apidoc/modules.html`.
+	./script/make_utils/fix_api_readme_reference.sh docs-copy
 	@# Fix not-compatible paths
 	./script/make_utils/fix_gitbook_paths.sh docs-copy
-	@# Fixing cardboard
-	poetry run python script/doc_utils/fix_gitbook_table.py --files docs-copy/getting-started/showcase.md
 	@# Docs
 	cd docs-copy && poetry run "$(MAKE)" html SPHINXOPTS='-W --keep-going'
 	@# Copy images from GitBook
@@ -669,7 +671,7 @@ mdformat:
 # Remark we need to remove .md's in venv
 check_mdformat:
 	"$(MAKE)" mdformat
-	find docs -name "*.md" | grep -v docs/developer-guide/tmp.api_for_check | xargs git diff --quiet
+	find docs -name "*.md" | grep -v docs/references/tmp.api_for_check | xargs git diff --quiet
 
 .PHONY: benchmark # Perform benchmarks
 benchmark:

README.md

@@ -31,7 +31,7 @@ Concrete ML is designed with ease of use in mind. Data scientists can use models
 - **Built-in models**: Ready-to-use FHE-friendly models with a user interface that is equivalent to their the scikit-learn and XGBoost counterparts
 - **Customs models**: Concrete ML supports models that can use quantization-aware training. These are developed by the user using PyTorch or keras/tensorflow and are imported into Concrete ML through ONNX
 
-*Learn more about Concrete ML features in the [documentation](https://docs.zama.ai/concrete-ml/readme).*
+*Learn more about Concrete ML features in the [documentation](https://docs.zama.ai/concrete-ml).*
 <br></br>
 
 ### Use cases
@@ -211,7 +211,7 @@ Concrete ML built-in models have APIs that are almost identical to their scikit-
 - [\[Video tutorial\] How To Convert a Scikit-learn Model Into Its Homomorphic Equivalent](https://www.zama.ai/post/how-to-convert-a-scikit-learn-model-into-its-homomorphic-equivalent)
 - [Linear Regression Over Encrypted Data With Homomorphic Encryption](https://www.zama.ai/post/linear-regression-using-linear-svr-and-concrete-ml-homomorphic-encryption)
 - [How to Deploy a Machine Learning Model With Concrete ML](https://www.zama.ai/post/how-to-deploy-machine-learning-models-with-concrete-ml)
-- More [Built-in models tutorials](docs/built-in-models/ml_examples.md) and [Deep learning tutorials](docs/deep-learning/examples.md)
+- More [Built-in models tutorials](docs/tutorials/ml_examples.md) and [Deep learning tutorials](docs/tutorials/dl_examples.md)
 
 *Explore more useful resources in [Awesome Zama repo](https://github.com/zama-ai/awesome-zama)*
 <br></br>
@@ -241,7 +241,7 @@ To cite Concrete ML in academic papers, please use the following entry:
 
 ### Contributing
 
-To contribute to Concrete ML, please refer to [this section of the documentation](docs/developer-guide/contributing.md).
+To contribute to Concrete ML, please refer to [this section of the documentation](docs/developer/contributing.md).
 <br></br>
 
 ### License

docs/README.md

@@ -1,118 +1,46 @@
-# What is Concrete ML?
+---
+description: >-
+  Concrete ML is an open-source, privacy-preserving, machine learning framework
+  based on Fully Homomorphic Encryption (FHE).
+---
 
-[⭐️ Star the repo on Github](https://github.com/zama-ai/concrete-ml) | [🗣 Community support forum](https://community.zama.ai/c/concrete-ml/8) | [📁 Contribute to the project](developer-guide/contributing.md)
+# Welcome
 
-![](.gitbook/assets/3.png)
+## Start here
 
-Concrete ML is an open source, privacy-preserving, machine learning framework based on Fully Homomorphic Encryption (FHE). It enables data scientists without any prior knowledge of cryptography to automatically turn machine learning models into their FHE equivalent, using familiar APIs from scikit-learn and PyTorch (see how it looks for [linear models](built-in-models/linear.md), [tree-based models](built-in-models/tree.md), and [neural networks](built-in-models/neural-networks.md)). Concrete ML supports converting models for inference with FHE but can also [train some models](built-in-models/training.md) on encrypted data.
+Learn the basics of Concrete ML, set it up, and make it run with ease.
 
-Fully Homomorphic Encryption is an encryption technique that allows computing directly on encrypted data, without needing to decrypt it. With FHE, you can build private-by-design applications without compromising on features. You can learn more about FHE in [this introduction](https://www.zama.ai/post/tfhe-deep-dive-part-1) or by joining the [FHE.org](https://fhe.org) community.
+<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>What is Concrete ML</strong></td><td><a href=".gitbook/assets/getstarted1.jpg">getstarted1.jpg</a></td><td><a href="getting-started/">getting-started</a></td></tr><tr><td><strong>Installation</strong></td><td><a href=".gitbook/assets/getstarted2.jpg">getstarted2.jpg</a></td><td><a href="getting-started/pip_installing.md">pip_installing.md</a></td></tr><tr><td><strong>Key concepts</strong></td><td><a href=".gitbook/assets/getstarted3.jpg">getstarted3.jpg</a></td><td><a href="getting-started/concepts.md">concepts.md</a></td></tr></tbody></table>
 
-Training on encrypted data provides the highest level of privacy but is slower than training on clear data. Federated learning is an alternative approach, where data privacy can be ensured by using a trusted gradient aggregator, coupled with optional _differential privacy_ instead of encryption. Concrete ML
-can import linear models, including logistic regression, that are trained using federated learning using the [`from_sklearn` function](./built-in-models/linear.md#pre-trained-models).
+## Build with Concrete ML
 
-## Example usage
+Start building with Concrete ML by exploring its core features, discovering essential guides, and learning more with user-friendly tutorials.
 
-Here is a simple example of classification on encrypted data using logistic regression. More examples can be found [here](built-in-models/ml_examples.md).
+<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><strong>Fundamentals</strong></td><td>Explore core features and basics of Concrete ML.</td><td><ul><li><a href="tutorials/ml_examples.md">Build-in models</a></li><li><a href="tutorials/dl_examples.md">Deep learning</a></li></ul></td><td></td><td><a href=".gitbook/assets/fundamentals.jpg">fundamentals.jpg</a></td></tr><tr><td><strong>Guides</strong></td><td>Discover essential guides to work with Concrete ML.</td><td><ul><li><a href="guides/prediction_with_fhe.md">Prediction with FHE</a></li><li><a href="guides/client_server.md">Production deployment</a></li><li><a href="guides/hybrid-models.md">Hybrid models</a></li></ul></td><td></td><td><a href=".gitbook/assets/guides.jpg">guides.jpg</a></td></tr><tr><td><strong>Tutorials</strong></td><td>Learn more about Concrete ML with our tutorials.</td><td><ul><li><a href="tutorials/showcase.md#start-here">Start here</a></li><li><a href="tutorials/showcase.md#go-further">Go further</a></li><li><a href="tutorials/showcase.md">See all tutorials</a></li></ul></td><td></td><td><a href=".gitbook/assets/tutorials.jpg">tutorials.jpg</a></td></tr></tbody></table>
 
-```python
-from sklearn.datasets import make_classification
-from sklearn.model_selection import train_test_split
-from concrete.ml.sklearn import LogisticRegression
+## References & Explanations
 
-# Lets create a synthetic data-set
-x, y = make_classification(n_samples=100, class_sep=2, n_features=30, random_state=42)
+Refer to the API, review product architecture, and access additional resources for in-depth explanations while working with Concrete ML.
 
-# Split the data-set into a train and test set
-X_train, X_test, y_train, y_test = train_test_split(
-    x, y, test_size=0.2, random_state=42
-)
+- [API](references/api/README.md)
+- [Quantization](explanations/quantization.md)
+- [Pruning](explanations/pruning.md)
+- [Compilation](explanations/compilation.md)
+- [Advanced features](explanations/advanced_features.md)
+- [Project architecture](explanations/inner-workings/)
 
-# Now we train in the clear and quantize the weights
-model = LogisticRegression(n_bits=8)
-model.fit(X_train, y_train)
+## Supports
 
-# We can simulate the predictions in the clear
-y_pred_clear = model.predict(X_test)
+Ask technical questions and discuss with the community. Our team of experts usually answers within 24 hours in working days.
 
-# We then compile on a representative set
-model.compile(X_train)
+- [Community forum](https://community.zama.ai/)
+- [Discord channel](https://discord.fhe.org/)
 
-# Finally we run the inference on encrypted inputs
-y_pred_fhe = model.predict(X_test, fhe="execute")
+## Developers
 
-print(f"In clear  : {y_pred_clear}")
-print(f"In FHE    : {y_pred_fhe}")
-print(f"Similarity: {(y_pred_fhe == y_pred_clear).mean():.1%}")
+Collaborate with us to advance the FHE spaces and drive innovation together.
 
-# Output:
-    # In clear  : [0 0 0 0 1 0 1 0 1 1 0 0 1 0 0 1 1 1 0 0]
-    # In FHE    : [0 0 0 0 1 0 1 0 1 1 0 0 1 0 0 1 1 1 0 0]
-    # Similarity: 100.0%
-```
-
-It is also possible to call encryption, model prediction, and decryption functions separately as follows.
-Executing these steps separately is equivalent to calling `predict_proba` on the model instance.
-
-<!--pytest-codeblocks:cont-->
-
-```python
-# Predict probability for a single example
-y_proba_fhe = model.predict_proba(X_test[[0]], fhe="execute")
-
-# Quantize an original float input
-q_input = model.quantize_input(X_test[[0]])
-
-# Encrypt the input
-q_input_enc = model.fhe_circuit.encrypt(q_input)
-
-# Execute the linear product in FHE 
-q_y_enc = model.fhe_circuit.run(q_input_enc)
-
-# Decrypt the result (integer)
-q_y = model.fhe_circuit.decrypt(q_y_enc)
-
-# De-quantize and post-process the result
-y0 = model.post_processing(model.dequantize_output(q_y))
-
-print("Probability with `predict_proba`: ", y_proba_fhe)
-print("Probability with encrypt/run/decrypt calls: ", y0)
-```
-
-This example shows the typical flow of a Concrete ML model:
-
-- The model is trained on unencrypted (plaintext) data using scikit-learn. As FHE operates over integers, Concrete ML quantizes the model to use only integers during inference.
-- The quantized model is compiled to an FHE equivalent. Under the hood, the model is first converted to a Concrete Python program, then compiled.
-- Inference can then be done on encrypted data. The above example shows encrypted inference in the model-development phase. Alternatively, during [deployment](getting-started/cloud.md) in a client/server setting, the data is encrypted by the client, processed securely by the server, and then decrypted by the client.
-
-## Current limitations
-
-To make a model work with FHE, the only constraint is to make it run within the supported precision limitations of Concrete ML (currently 16-bit integers). Thus, machine learning models must be quantized, which sometimes leads to a loss of accuracy versus the original model, which operates on plaintext.
-
-Additionally, Concrete ML currently only supports training on encrypted data for some models, while it supports _inference_ for a large variety of models.
-
-Finally, there is currently no support for pre-processing model inputs and post-processing model outputs. These processing stages may involve text-to-numerical feature transformation, dimensionality reduction, KNN or clustering, featurization, normalization, and the mixing of results of ensemble models.
-
-These issues are currently being addressed, and significant improvements are expected to be released in the near future.
-
-## Concrete stack
-
-Concrete ML is built on top of Zama's [Concrete](https://github.com/zama-ai/concrete).
-
-## Online demos and tutorials
-
-Various tutorials are available for [built-in models](built-in-models/ml_examples.md) and [deep learning](deep-learning/examples.md). Several stand-alone demos for use cases can be found in the [Demos and Tutorials](getting-started/showcase.md) section.
-
-If you have built awesome projects using Concrete ML, feel free to let us know and we'll link to your work!
-
-## Additional resources
-
-- [Dedicated Concrete ML community support](https://community.zama.ai/c/concrete-ml/8)
-- [Zama's blog](https://www.zama.ai/blog)
-- [FHE.org community](https://fhe.org)
-
-## Support
-
-- Support forum: [https://community.zama.ai](https://community.zama.ai) (we answer in less than 24 hours).
-- Live discussion on the FHE.org Discord server: [https://discord.fhe.org](https://discord.fhe.org) (inside the #**concrete** channel).
-- Do you have a question about Zama? Write us on [Twitter](https://twitter.com/zama_fhe) or send us an email at: **[email protected]**
+- [Contribute to Concrete ML](developer/contributing.md)
+- [Check the latest release note](https://github.com/zama-ai/concrete-ml/releases)
+- [Request a feature](https://github.com/zama-ai/concrete-ml/issues/new?assignees=&labels=feature&projects=&template=feature_request.md)
+- [Report a bug](https://github.com/zama-ai/concrete-ml/issues/new?assignees=&labels=bug&projects=&template=bug_report.md)