From 7e1d81161053e14769a448145f4a27531d29fa7d Mon Sep 17 00:00:00 2001 From: Adrien Matissart Date: Thu, 2 May 2024 11:28:03 +0200 Subject: [PATCH] [solidago] init docs content and use mkdocs to build docs pages --- solidago/docs/hooks.py | 15 +++ solidago/docs/index.md | 56 ++++++++++ solidago/docs/modules/aggregation.md | 0 solidago/docs/modules/post_process.md | 0 solidago/docs/modules/preference_learning.md | 3 + solidago/docs/modules/scaling.md | 0 solidago/docs/modules/trust_propagation.md | 6 + solidago/docs/modules/voting_rights.md | 3 + solidago/docs/pipeline.md | 17 +++ solidago/docs/tournesol.md | 0 solidago/experiments/tournesol.py | 13 +-- solidago/mkdocs.yml | 109 +++++++++++++++++++ solidago/pyproject.toml | 5 + 13 files changed, 215 insertions(+), 12 deletions(-) create mode 100644 solidago/docs/hooks.py create mode 100644 solidago/docs/index.md create mode 100644 solidago/docs/modules/aggregation.md create mode 100644 solidago/docs/modules/post_process.md create mode 100644 solidago/docs/modules/preference_learning.md create mode 100644 solidago/docs/modules/scaling.md create mode 100644 solidago/docs/modules/trust_propagation.md create mode 100644 solidago/docs/modules/voting_rights.md create mode 100644 solidago/docs/pipeline.md create mode 100644 solidago/docs/tournesol.md create mode 100644 solidago/mkdocs.yml diff --git a/solidago/docs/hooks.py b/solidago/docs/hooks.py new file mode 100644 index 0000000000..11e357b9ba --- /dev/null +++ b/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 diff --git a/solidago/docs/index.md b/solidago/docs/index.md new file mode 100644 index 0000000000..d5816a2c12 --- /dev/null +++ b/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. --> diff --git a/solidago/docs/modules/aggregation.md b/solidago/docs/modules/aggregation.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/solidago/docs/modules/post_process.md b/solidago/docs/modules/post_process.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/solidago/docs/modules/preference_learning.md b/solidago/docs/modules/preference_learning.md new file mode 100644 index 0000000000..c738ea5292 --- /dev/null +++ b/solidago/docs/modules/preference_learning.md @@ -0,0 +1,3 @@ +::: solidago.preference_learning + options: + show_if_no_docstring: false diff --git a/solidago/docs/modules/scaling.md b/solidago/docs/modules/scaling.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/solidago/docs/modules/trust_propagation.md b/solidago/docs/modules/trust_propagation.md new file mode 100644 index 0000000000..b2655c0ad7 --- /dev/null +++ b/solidago/docs/modules/trust_propagation.md @@ -0,0 +1,6 @@ +::: solidago.trust_propagation + options: + show_if_no_docstring: false + + + diff --git a/solidago/docs/modules/voting_rights.md b/solidago/docs/modules/voting_rights.md new file mode 100644 index 0000000000..c6dd7502fc --- /dev/null +++ b/solidago/docs/modules/voting_rights.md @@ -0,0 +1,3 @@ +::: solidago.voting_rights + options: + show_if_no_docstring: false diff --git a/solidago/docs/pipeline.md b/solidago/docs/pipeline.md new file mode 100644 index 0000000000..50a655406c --- /dev/null +++ b/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 + + + diff --git a/solidago/docs/tournesol.md b/solidago/docs/tournesol.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/solidago/experiments/tournesol.py b/solidago/experiments/tournesol.py index 9317a5c41c..d219a1b838 100644 --- a/solidago/experiments/tournesol.py +++ b/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() diff --git a/solidago/mkdocs.yml b/solidago/mkdocs.yml new file mode 100644 index 0000000000..c109676988 --- /dev/null +++ b/solidago/mkdocs.yml @@ -0,0 +1,109 @@ +site_name: "Solidago | a toolbox for Solid Algorithmic Governance" +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/ diff --git a/solidago/pyproject.toml b/solidago/pyproject.toml index c1588faa7b..b382b92d97 100644 --- a/solidago/pyproject.toml +++ b/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", ]