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

solidago/docs/hooks.py

@@ -0,0 +1,15 @@
+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.abs_url == '/':
+        version_str = f'> Documentation for version: **{__version__}**'
+        markdown = re.sub(r'{{ *version *}}', version_str, markdown)
+    return markdown

solidago/docs/index.md

@@ -0,0 +1,56 @@
+# solidago
+
+[![pypi](https://img.shields.io/pypi/v/solidago.svg)](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)
+
+**Soli**d **A**lgorithmic **Go**vernance used by the Tournesol platform
+
+{{ version }}
+
+
+
+## Usage
+
+Here are some examples of what **solidago** can do:
+
+```py title="Pipeline Usage"
+from solidago import Pipeline
+# TODO
+```
+
+## Installation
+
+**solidago** requires **Python >= 3.9**
+
+### From PyPI
+
+Using `pip`:
+
+```bash
+pip install solidago
+```
+
+
+### From source
+
+_TODO_
+
+
+
+# Welcome to MkDocs
+
+For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+
+## Commands
+
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
+
+## Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files. -->

solidago/docs/modules/preference_learning.md

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

solidago/docs/modules/trust_propagation.md

@@ -0,0 +1,6 @@
+::: solidago.trust_propagation
+    options:
+        show_if_no_docstring: false
+
+
+<!-- ::: solidago.trust_propagation.TrustPropagation -->

solidago/docs/modules/voting_rights.md

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

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/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 = TournesolInputFromPublicDataset.download()

solidago/mkdocs.yml

@@ -0,0 +1,109 @@
+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
+  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:
+  - Introduction: "index.md"
+  - Pipeline: "pipeline.md"
+  - Modules: 
+    - "modules/trust_propagation.md"
+    - "modules/voting_rights.md"
+    - "modules/preference_learning.md"
+    - "modules/scaling.md"
+    - "modules/aggregation.md"
+    - "modules/post_process.md"
+  - Tournesol dataset: "tournesol.md"
+
+
+markdown_extensions:
+  - toc:
+      permalink: true
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  # - 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
+          import:
+            - 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/

solidago/pyproject.toml

@@ -29,6 +29,11 @@ dynamic = ["version"]
 "Bug Tracker" = "https://github.com/tournesol-app/tournesol/issues"
 
 [project.optional-dependencies]
+docs = [
+    "mkdocs-material==9.*",
+    "mkdocstrings-python",
+    "markdown-include"
+]
 test = [
     "pytest >=7.1.3,<8.0.0",
 ]