Repo documentation

themoenen · themoenen · commit e0feab7e429b · 2025-04-17T12:32:45.000+03:00
diff --git a/README.md b/README.md
@@ -17,6 +17,23 @@ This repo holds the OpenAD website:
 
 ## Development
 
+### Auto-generated content
+
+Some of the documentation pages are automatically generated or updated by the `generate_docs()` script.  
+Jump to the [/generator](generator) directory for details.
+
+Documentation pages are generated by script:
+- [Publicly Available Models](https://openad.accelerate.science/docs/model-service/deploying-models)
+- [OpenAD Commands](https://openad.accelerate.science/docs/commands)
+- [Base Concepts](https://openad.accelerate.science/docs/base-concepts)
+
+Documentation pages that have descriptions that are updated by script:
+- [OpenAD Plugins](https://openad.accelerate.science/docs/plugins)
+
+Other files that are generated or updated by the script:
+- [README.md](https://github.com/acceleratedscience/openad-toolkit?tab=readme-ov-file#readme) for the openad-toolkit repo
+- [commands.csv](generator/_output/other/commands.csv) overview file
+
 ### Development Server
 
 Run the development server at [localhost:8000](http://localhost:8000)
diff --git a/generator/_input/model-service~available-models.md b/generator/_input/model-service~available-models.md
@@ -0,0 +1,8 @@
+{{DO_NOT_EDIT}}
+
+# Publicly Available Models
+
+Below an overview of our available open-source models. Find them on [GitHub here](https://github.com/orgs/acceleratedscience/repositories?q=%22openad-service-%22).  
+Go to [Deploying Models](deploying-models.md) for more detailed deployment options beyond the quick-start.
+
+<br><br>
diff --git a/generator/_output/openad-toolkit/README.md b/generator/_output/openad-toolkit/README.md
@@ -0,0 +1,73 @@
+<!-- autogenerated:notion -->
+<!--
+
+Attention
+---------
+One or more descriptions in this file have been auto-generated
+by the generate_docs() script in @openad-website/generator.
+
+For more info:
+https://github.com/acceleratedscience/openad-website/tree/generator
+
+-->
+<!-- /autogenerated:notion -->
+
+<!--
+
+Attention:
+The desciption in this file is auto-generated by the
+generatce_docs script in the openad-toolkit repo.
+
+For more info:
+https://github.com/acceleratedscience/openad-toolkit/tree/main/docs
+
+-->
+
+<img src="assets/molecule-header.jpg" width="830" alt="OpenAD" />
+
+# OpenAD
+
+**Open Source Molecular & Materials Research Toolkit**
+
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/openad)](https://pypi.org/project/openad/)
+[![PyPI version](https://img.shields.io/pypi/v/openad)](https://pypi.org/project/openad/)
+[![License MIT](https://img.shields.io/github/license/acceleratedscience/openad-toolkit)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+<!-- autogenerated:description -->
+OpenAD is an intuitive toolkit that simplifies access to a variety of AI models and services for scientific discovery. Together with its convenient visualisation capabilities, OpenAD empowers scientists across industries to enhance their discovery process.
+
+OpenAD is designed to integrate into your existing workflows via Jupyter Notebook, CLI or API, using a low-code approach to accelerate your research.
+<!-- /autogenerated:description -->
+
+[![image](assets/home.svg)](https://openad.accelerate.science)
+[![image](assets/docs.svg)](https://openad.accelerate.science/docs/getting-started)
+[![image](assets/tutorials.svg)](https://openad.accelerate.science/blog/category/tutorials)
+<!-- [![image](assets/install.svg)](https://openad.accelerate.science/docs/installation) -->
+<br><br>
+
+
+## Quick Install
+
+> [!TIP]
+> To install OpenAD inside a virtual environment, please consult the [Installation](https://openad.accelerate.science/docs/installation) guide.
+
+    pip install openad
+    openad
+
+Get started with Jupyter Notebook examples:
+
+    init_magic
+    init_examples
+    jupyter lab ~/openad_notebooks/Table_of_Contents.ipynb
+
+If you get an error when running `init_magic`, you may first need to setup the default iPython profile for magic commands.
+
+    ipython profile create
+
+<br><br>
+
+## Release Notes
+
+`0.7.5`
+- We have retired the RXN and Deep Search toolkits and replaced them with new and more user-friendly [plugins](README/plugins.md).
diff --git a/generator/methods/generate_commands_csv.py b/generator/methods/generate_commands_csv.py
@@ -10,10 +10,17 @@
 from .shared import write_output_file
 
 
-# Loop through all commands and export them to a CSV file.
-# This is not used for anything in particular, other than
-# to have a list of all commands in a file which can be annotated.
 def generate_commands_csv(filename="commands.csv", delimiter=";"):
+    """
+    Create a CSV with all OpenAD commands.
+
+    This is not used for anything in particular, other than
+    to have a list of all commands in a file which can be annotated.
+
+    - Loop through all toolkit commands and compile CSV
+    - Store CSV in _output/other/commands.csv
+    """
+
     output_text(
         "<h1>Generating <yellow>commands.csv</yellow> from help</h1>", pad_top=2
     )
diff --git a/generator/methods/generate_commands_md.py b/generator/methods/generate_commands_md.py
@@ -6,8 +6,15 @@
 from .shared import DO_NOT_EDIT, read_input_file, write_output_file
 
 
-# Loop through all commands and export them to docs/commands.md
 def generate_commands_md(filename="commands.md"):
+    """
+    Generate the commands.md page for the documentation.
+
+    - Start from the _input/commands.md template
+    - Loop through all OpenAD commands & generate markdown
+    - Store result in _output/docs/commands.md
+    """
+
     output_text(f"<h1>Generating <yellow>{filename}</yellow> from help</h1>", pad_top=2)
 
     toc = []  # Table of content
diff --git a/generator/methods/generate_model_docs.py b/generator/methods/generate_model_docs.py
@@ -19,21 +19,42 @@
 
 def generate_model_docs(filename="model-service~available-models.md"):
     """
-    Generate output/available-models.md page for documentation website.
+    Generate the available-models.md page for the documentation.
+
+    - Start from the _input/model-service~available-models.md template
+    - Load the models.csv file from _input/models.csv
+    - Scrape the README.md files from the GitHub repositories listed in models.csv
+    - Generate overview markdown for each model
+    - Store result in _output/docs/model-service~available-models.md
+
+    Note: The copy_docs script will interpret the ~ in the filename to know
+    the path in the /docs directory where to copy the file to.
     """
 
     output_text(
         f"<h1>Generating <yellow>{filename}</yellow> from input/models.csv</h1>",
         pad_top=2,
     )
 
+    # Read commands.md input content
+    available_models_md = read_input_file(filename)
+
+    # Insert DO NOT EDIT comment
+    available_models_md = re.sub(
+        r"{{DO_NOT_EDIT}}", DO_NOT_EDIT, available_models_md, flags=re.DOTALL
+    )
+
+    # Scrape README.md files from GitHub
     model_data = scrape_repos()
     if not model_data:
         return
-    # print(model_data)
+
+    # Generate markdown
     markdown = generate_md(model_data)
-    markdown = DO_NOT_EDIT + "\n\n# Publicly Available Models\n\n" + markdown
-    write_output_file("docs/" + filename, markdown)
+
+    # Insert in template and save
+    available_models_md = available_models_md + "\n\n" + markdown
+    write_output_file("docs/" + filename, available_models_md)
 
     # for model in model_data:
     #     output_text(f"<yellow>Name:</yellow> {model['name']}", pad_top=1)
@@ -213,16 +234,16 @@ def generate_md(model_data):
             if model["support:compose"]
             else "--REMOVE-LINE--"
         )
-        instructions_url_container = "/docs/model-service/prepackaged-models/#deployment-via-container"
-        instructions_url_compose = "/docs/model-service/prepackaged-models/#deployment-via-container-composeyml"
+        instructions_url_container = "/docs/model-service/deploying-models/#deployment-via-container"
+        instructions_url_compose = "/docs/model-service/deploying-models/#deployment-via-container-composeyaml-recommended"
         instructions_url = instructions_url_compose if model["support:compose"] else instructions_url_container
         btn_instructions = f"[Instructions]({instructions_url}){{ .md-button .md-button--tertiary }}  "
         support_overview = (
             f"\n"
             "Support for:  \n"
             f"{'❌' if not model['support:compose'] else '✅'} Docker / Podman Compose  \n"
             f"{'❌' if not model['support:docker'] else '✅'} Docker / Podman  \n"
-            f"{'❌' if model['support:apple-silicon'] is False else '❓' if model['support:apple-silicon'] is None else '✅'} Apple Silicon - [more info](/docs/model-service/prepackaged-models/#apple-silicon)  \n"
+            f"{'❌' if model['support:apple-silicon'] is False else '❓' if model['support:apple-silicon'] is None else '✅'} Apple Silicon - [more info](/docs/model-service/deploying-models#apple-silicon)  \n"
             f"\n"
         )
         # fmt:on
@@ -277,7 +298,7 @@ def generate_md(model_data):
 
         # Compile
         html_block = [
-            f"<details markdown><summary><h3>{title}</h3></summary>",
+            f"<details markdown><summary><h4>{title}</h4></summary>",
             "<div markdown>",
             "",
             # Buttons
diff --git a/generator/methods/update_base_concepts_md.py b/generator/methods/update_base_concepts_md.py
@@ -7,8 +7,15 @@
 from openad.helpers.output import output_text
 
 
-# Generate the docs/base-concepts.md file with the concept descriptions
 def update_base_concepts_md(filename="base-concepts.md"):
+    """
+    Update the base-concepts.md page for the documentation.
+
+    - Copy the content of the current version of the page in /docs
+    - Update the page with the latest concept descriptions from the _source description files
+    - Store result in _output/docs/base-concepts.md
+    """
+
     output_text(f"<h1>Generating <yellow>{filename}</yellow></h1>", pad_top=2)
 
     # Read base file content
diff --git a/generator/methods/update_gh_readme.py b/generator/methods/update_gh_readme.py
@@ -7,8 +7,18 @@
 from openad.helpers.output import output_text
 
 
-# Update the main README.md for the openad-toolkit repo with OpenAD description
 def update_gh_readme(filename="README.md"):
+    """
+    Update the main README.md for the openad-toolkit repo with the latest OpenAD description.
+
+    WARNING: this will fetch the README.md from the current main branch of the
+    openad-toolkit repo. If you have local changes, they will be overwritten.
+
+    - Copy the content of the current README.md on the main branch of the openad-toolkit repo.
+    - Update the page with the latest OpenAD description from the _source/description.txt file.
+    - Store result in _output/openad-toolkit/README.md
+    """
+
     output_text(
         f"<h1>Updating <yellow>{filename}</yellow> with OpenAD description</h1>",
         pad_top=2,
diff --git a/generator/methods/update_plugins_md.py b/generator/methods/update_plugins_md.py
@@ -9,6 +9,14 @@
 
 # Update the docs/plugins.md file with the about_plugins description
 def update_plugins_md(filename="plugins.md"):
+    """
+    Update the plugins.md file with the latest plugin description for the documentation.
+
+    - Copy the content of the current version of the page in /docs
+    - Update the page with the latest plugin description from the _source/about_plugins.txt file
+    - Store result in _output/docs/plugins.md
+    """
+
     output_text(
         f"<h1>Updating <yellow>{filename}</yellow> with about_plugins description</h1>",
         pad_top=2,
diff --git a/main/docs/model-service/available-models.md b/main/docs/model-service/available-models.md
diff --git a/main/docs/model-service/deploying-models.md b/main/docs/model-service/deploying-models.md
