[solidago] init docs content and use mkdocs to build docs pages

.github/workflows/solidago-publish.yml

@@ -15,7 +15,7 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python
         uses: actions/setup-python@v4
@@ -33,3 +33,9 @@ jobs:
         with:
           packages-dir: solidago/dist/
           password: ${{ secrets.SOLIDAGO_PYPI_API_TOKEN }}
+
+      - name: Publish documentation on GitHub Pages
+        run: |
+          pip install -e .[docs]
+          git fetch origin gh-pages
+          mkdocs gh-deploy

solidago/.gitignore

@@ -1,5 +1,6 @@
 /devenv/
 /dist/
+/site/
 **__pycache__/
 .flake8/
 .pylint/

solidago/README.md

@@ -1,18 +1,14 @@
 # Solidago
-**Solid** **A**lgorithmic **Go**vernance, used by the Tournesol platform
 
-<a href="https://pypi.org/project/solidago" target="_blank">
-    <img src="https://img.shields.io/pypi/v/solidago?color=%2334D058" alt="Package version">
-</a>
-<a href="#copyright--license">
-    <img alt="PyPI - License" src="https://img.shields.io/pypi/l/solidago">
-</a>
+[![PyPi](https://img.shields.io/pypi/v/solidago)](https://pypi.org/project/solidago)
+[![License](https://img.shields.io/pypi/l/solidago.svg)](https://github.com/tournesol-app/tournesol/tree/main/solidago#copyright--license)
+[![CI status](https://github.com/tournesol-app/tournesol/actions/workflows/solidago-test.yml/badge.svg)](https://github.com/tournesol-app/tournesol/actions/workflows/solidago-test.yml)
 
+A toolbox for **Solid** **A**lgorithmic **Go**vernance, used by the Tournesol platform.
 
-## Publish a new release
+**Documentation**: https://solidago.tournesol.app
 
-1. In a Pull Request, update the version number in [`./src/solidago/__version__.py`](./src/solidago/__version__.py)
-2. The package will be published automatically when the new version is merged into "main", by [this Github Action](../.github/workflows/solidago-publish.yml).
+---
 
 ## Tests
 
@@ -26,6 +22,7 @@ pytest
 Depending on the platform, you may need to replace ```source devenv/bin/activate``` by another call.
 See the [venv doc](https://docs.python.org/3/library/venv.html#how-venvs-work) for more information.
 
+
 ## Synthetic experiments
 
 To run experiments, once the virtual environement setup, you may run the experiments on synthetic data using.
@@ -38,6 +35,12 @@ You may modify the experiments by editing ```experiments/resilience.json```,
 or by creating a new ```.json``` file.
 
 
+## Publish a new release
+
+1. In a Pull Request, update the version number in [`./src/solidago/__version__.py`](./src/solidago/__version__.py)
+2. The package will be published automatically when the new version is merged into "main", by [this Github Action](../.github/workflows/solidago-publish.yml).
+
+
 ## Copyright & License
 
 Copyright 2023 Tournesol Association and contributors.

solidago/docs/CNAME

@@ -0,0 +1 @@
+solidago.tournesol.app

solidago/docs/hooks.py

@@ -0,0 +1,18 @@
+import re
+
+from mkdocs.config import Config
+from mkdocs.structure.files import Files
+from mkdocs.structure.pages import Page
+
+from solidago import __version__
+
+
+def on_page_markdown(markdown: str, page: Page, config: Config, files: Files) -> str:
+    # Add Solidago version in homepage
+    if page.file.src_uri == "index.md":
+        version_str = f'''
+!!! info "Version"
+    This documentation has been generated from version **{__version__}**.
+'''
+        markdown = re.sub(r'{{ *version *}}', version_str, markdown)
+    return markdown

solidago/docs/index.md

@@ -0,0 +1,54 @@
+# solidago [![pypi](https://img.shields.io/pypi/v/solidago.svg?color=%2334D058)](https://pypi.python.org/pypi/solidago) [![license](https://img.shields.io/pypi/l/solidago)](https://github.com/tournesol-app/tournesol/blob/main/solidago/README.md#copyright--license)
+
+A toolbox for **Soli**d **A**lgorithmic **Go**vernance, used by the [Tournesol](https://tournesol.app) platform.
+
+{{ version }}
+
+
+## Usage
+
+```py title="Pipeline Usage"
+import logging
+from solidago.pipeline import Pipeline
+from solidago.pipeline.inputs import TournesolDataset
+from solidago.pipeline.outputs import PipelineOutputInMemory
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+
+# Initialize pipeline with its input and output
+tournesol_dataset = TournesolDataset.download()
+pipeline = Pipeline()
+output = PipelineOutputInMemory()
+
+# Run pipeline
+pipeline.run(
+    input=tournesol_dataset,
+    output=output,
+    criterion="largely_recommended",
+)
+
+# Access results
+print(output.individual_scores)
+print(output.entity_scores)
+```
+
+## Installation
+
+**`solidago`** requires **Python >= 3.9**
+
+### From PyPI
+
+Using `pip`:
+
+```bash
+pip install solidago
+```
+
+### From source
+
+To install `solidago` from branch "main":
+
+```bash
+pip install "git+https://github.com/tournesol-app/tournesol.git@main#egg=solidago&subdirectory=solidago"
+```

solidago/docs/javascripts/mathjax.js

@@ -0,0 +1,19 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => {
+  MathJax.startup.output.clearCache()
+  MathJax.typesetClear()
+  MathJax.texReset()
+  MathJax.typesetPromise()
+})

solidago/docs/modules/aggregation.md

@@ -0,0 +1,3 @@
+::: solidago.aggregation
+    options:
+        show_if_no_docstring: false

solidago/docs/modules/post_process.md

@@ -0,0 +1,3 @@
+::: solidago.post_process
+    options:
+        show_if_no_docstring: false

solidago/docs/modules/preference_learning.md

@@ -0,0 +1,3 @@
+::: solidago.preference_learning
+    options:
+        show_if_no_docstring: false

solidago/docs/modules/scaling.md

@@ -0,0 +1 @@
+::: solidago.scaling

solidago/docs/modules/trust_propagation.md

@@ -0,0 +1,3 @@
+::: solidago.trust_propagation
+
+

solidago/docs/modules/voting_rights.md

@@ -0,0 +1,2 @@
+::: solidago.voting_rights
+

solidago/docs/overrides/main.html

@@ -0,0 +1,11 @@
+{% extends "base.html" %}
+
+{% block htmltitle %}
+{% if page.meta and page.meta.title %}
+  <title>{{ page.meta.title }} - {{ config.extra.site_title }}</title>
+{% elif page.title and not page.is_homepage %}
+  <title>{{ page.title | striptags }} - {{ config.extra.site_title }}</title>
+{% else %}
+  <title>{{ config.extra.site_title }}</title>
+{% endif %}
+{% endblock %}

solidago/docs/pipeline.md

@@ -0,0 +1,17 @@
+# Pipeline
+
+::: solidago.pipeline.Pipeline
+    options:
+        show_root_heading: true
+        show_root_full_path: false
+        show_if_no_docstring: false
+
+
+::: solidago.pipeline.DefaultPipeline
+    options:
+        show_signature: false
+        show_root_heading: true
+        show_root_full_path: false
+
+
+<!-- ::: solidago.pipeline -->

solidago/docs/primitives.md

@@ -0,0 +1 @@
+::: solidago.primitives

solidago/docs/structures/privacy_settings.md

@@ -0,0 +1,2 @@
+::: solidago.privacy_settings
+

solidago/docs/structures/scoring_model.md

@@ -0,0 +1,2 @@
+::: solidago.scoring_model
+

solidago/docs/tournesol.md

@@ -0,0 +1,18 @@
+# Using Tournesol dataset with Solidago
+
+An instance of `TournesolDataset` can be used as a pipeline input in Solidago.
+
+```py
+from solidago.pipeline.inputs import TournesolDataset
+
+# Download the latest dataset from Tournesol API.
+pipeline_input = TournesolDataset.download()
+
+# Read a local file
+pipeline_input = TournesolDataset("path/to/dataset.zip")
+```
+
+::: solidago.pipeline.inputs
+    options:
+        members:
+            - TournesolDataset

solidago/experiments/tournesol.py

@@ -16,20 +16,9 @@
 from solidago.pipeline import Pipeline
 
 
+logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
-info_loggers = [
-    __name__, 
-    "solidago.pipeline.pipeline", 
-    "solidago.scaling.mehestan",
-    "solidago.preference_learning.base"
-]
-for module in info_loggers:
-    info_logger = logging.getLogger(module)
-    info_logger.setLevel(logging.INFO)
-    ch = logging.StreamHandler()
-    ch.setLevel(logging.INFO)
-    info_logger.addHandler(ch)
 
 logger.info("Retrieve public dataset")
 inputs = TournesolDataset.download()

solidago/mkdocs.yml

@@ -0,0 +1,123 @@
+site_name: "Solidago | <span style='font-weight: normal'>a toolbox for <b>Solid</b> <b>A</b>lgorithmic <b>Go</b>vernance</span>"
+site_description: "Solid Algorithmic Governance, used by the Tournesol platform"
+strict: true
+
+repo_name: tournesol > solidago
+repo_url: https://github.com/tournesol-app/tournesol/tree/main/solidago
+
+theme:
+  name: material
+  custom_dir: docs/overrides
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: amber
+      toggle:
+        icon: material/lightbulb-outline
+        name: "Switch to dark mode"
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: amber
+      toggle:
+        icon: material/lightbulb
+        name: "Switch to light mode"
+  features:
+    # - content.code.annotate
+    - content.code.copy
+    # - navigation.tabs
+    - search.suggest
+    - search.highlight
+    - content.tabs.link
+    # - navigation.sections
+    - navigation.expand
+    # - toc.integrate 
+
+
+nav:
+  - Get Started: "index.md"
+  - Pipeline: "pipeline.md"
+  - Structures:
+    - "structures/scoring_model.md"
+    - "structures/privacy_settings.md"
+  - Modules: 
+    - "modules/trust_propagation.md"
+    - "modules/preference_learning.md"
+    - "modules/voting_rights.md"
+    - "modules/scaling.md"
+    - "modules/aggregation.md"
+    - "modules/post_process.md"
+  - Primitives: "primitives.md"
+  - Tournesol dataset: "tournesol.md"
+
+
+markdown_extensions:
+  - toc:
+      permalink: true
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.arithmatex:
+      generic: true
+  # - markdown_include.include:
+      # base_path: solidago
+
+plugins:
+  # - mike:
+  #     alias_type: symlink
+  #     canonical_version: latest
+  - search
+  # - exclude:
+  #     glob:
+  #     - theme/announce.html
+  #     - plugins/*
+  #     - __pycache__/*
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [.]
+          options:
+            show_symbol_type_heading: true
+            members_order: source
+            show_source: false
+            show_labels: false
+            separate_signature: true
+            filters: ["!^_", "^__", "!^__all__", "!__str__"]
+            docstring_options:
+              ignore_init_summary: false
+            merge_init_into_class: true
+            show_signature_annotations: true
+            signature_crossrefs: true
+            docstring_style: numpy
+            show_if_no_docstring: true
+            show_root_full_path: false
+            show_root_heading: false
+            show_root_toc_entry: false
+            # extensions:
+            #   - docs/plugins/griffe_doclinks.py
+          inventories:
+            - https://docs.python.org/3/objects.inv
+          # rendering:
+          #   show_root_heading: true
+          #   show_root_full_path: false
+          #   show_source: false
+          #   heading_level: 2
+          #   merge_init_into_class: true
+          #   show_signature_annotations: true
+          #   separate_signature: true
+
+hooks:
+ - 'docs/hooks.py'
+
+watch:
+ - src/
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.2.2/es5/tex-mml-chtml.min.js
+
+extra:
+  site_title: "Solidago"