Merge pull request #1206 from facebookresearch/update-architecture-di…

…agrams

Update architecture docs

.github/workflows/deploy-docs.yml

@@ -42,11 +42,7 @@ jobs:
 
       - name: 📝 Auto Generate Blueprint Docs
         run: |
-          cd ../../mephisto/scripts/local_db/gh_actions
-          python auto_generate_blueprint.py
-          python auto_generate_architect.py
-          python auto_generate_requester.py
-          python auto_generate_provider.py
+          mephisto scripts local_db auto_generate_all_docs_reference_md
       - name: Install dependencies
         run: yarn install --frozen-lockfile
       - name: Build website

docs/README.md

@@ -8,7 +8,7 @@
 
 - Looking to get set-up and running quickly with Mephisto? Check out the **[10 minute quickstart](https://mephisto.ai/docs/guides/quickstart)**.
 
-- Want to learn more about the different concepts within Mephisto and how they work together? The excellent and thorough **[architecture overview](https://mephisto.ai/docs/explanations/architecture_overview)** should serve as a great deep-dive and reference for beginners and advanced users alike.
+- Want to learn more about the different concepts within Mephisto and how they work together? The excellent and thorough **[architecture overview](https://mephisto.ai/docs/explanations/abstractions_overview)** should serve as a great deep-dive and reference for beginners and advanced users alike.
 
 ### Customization
 

docs/web/docs/explanations/architect_api.md

@@ -4,10 +4,10 @@
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 
-sidebar_position: 1
+sidebar_position: 2
 ---
 
-# Architects, Routers, and `mephisto-task`: The Architect API.
+# Architect API
 
 The Architect API is what allows Mephisto to completely abstract away the process of getting workers to operate in Mephisto tasks. In short, it aims to cover 4 primary functions:
 1. `Worker`/`Agent` registration and validation

docs/web/docs/guides/how_to_contribute/documentation.md

@@ -20,12 +20,15 @@ To run Mephisto docs on your local machine for development (with Docker), run th
 ```shell
 docker-compose -f docker/docker-compose.dev.yml up
 docker exec -it mephisto_dc bash
+mephisto scripts local_db auto_generate_all_docs_reference_md
 cd /mephisto/docs/web/
 yarn
 yarn install
 yarn start-dev:docker
 ```
 
+Then run `mephisto scripts local_db auto_generate_all_docs_reference_md` to auto-generate `.md` files in `docs/web/docs/reference` directory. (They will describe parameters of some Python classes.) Noe that on production this command is called by Github Actions.
+
 You will now be able to access docs in the browser on [http://localhost:3001/](http://localhost:3001/) with live updates after each saving files from docs.
 
 > NOTE: search will not be available in development mode. If you need to use search, stop development server and use production instruction below

docs/web/docs/guides/how_to_use/review_app/diagram.md

@@ -0,0 +1,13 @@
+---
+# Copyright (c) Meta Platforms and its affiliates.
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+sidebar_position: 5
+---
+
+# TaskReview app diagram
+
+Here is how TaskReview app works under the hood to enable review of Task results in a local web browser.
+
+![task_review_sequence_diagram.png](./screenshots/task_review_sequence_diagram.png)

docs/web/docs/reference/architects.md

@@ -1,63 +1,8 @@
 ---
-
 # Copyright (c) Meta Platforms and its affiliates.
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 
-sidebar_position: 2
 ---
 
-# Architects
-
-
-Architects contain the logic surrounding deploying a server that workers will be able to access.
-## mock
-
-
-
-
-|dest|type|default|help|choices|required|
-| :--- | :--- | :--- | :--- | :--- | :--- |
-|server_type|str|node|None|None|False|
-|server_source_path|str|???|Optional path to a prepared server directory containing everything needed to run a server of the given type. Overrides server type. |None|False|
-|should_run_server|bool|False|Addressible location of the server|None|False|
-|port|str|3000|Port to launch the server on|None|False|
-
-## local
-
-
-
-
-|dest|type|default|help|choices|required|
-| :--- | :--- | :--- | :--- | :--- | :--- |
-|server_type|str|node|None|None|False|
-|server_source_path|str|???|Optional path to a prepared server directory containing everything needed to run a server of the given type. Overrides server type. |None|False|
-|hostname|str|localhost|Addressible location of the server|None|False|
-|port|str|3000|Port to launch the server on|None|False|
-
-## heroku
-
-
-
-
-|dest|type|default|help|choices|required|
-| :--- | :--- | :--- | :--- | :--- | :--- |
-|server_type|str|node|None|None|False|
-|server_source_path|str|???|Optional path to a prepared server directory containing everything needed to run a server of the given type. Overrides server type. |None|False|
-|use_hobby|bool|False|Launch on the Heroku Hobby tier|None|False|
-|heroku_team|unknown|???|Heroku team to use for this launch|None|False|
-|heroku_app_name|unknown|???|Heroku app name to use for this launch|None|False|
-|heroku_config_args|unknown|{}|str:str dict containing all heroku config variables to set for the app|None|False|
-
-## ec2
-
-
-
-
-|dest|type|default|help|choices|required|
-| :--- | :--- | :--- | :--- | :--- | :--- |
-|server_type|str|node|None|None|False|
-|server_source_path|str|???|Optional path to a prepared server directory containing everything needed to run a server of the given type. Overrides server type. |None|False|
-|instance_type|str|t2.micro|Instance type to run router|None|False|
-|subdomain|str|The task name defined in your task's hydra config|Subdomain name for routing|None|False|
-|profile_name|str|???|Profile name for deploying an ec2 instance|None|False|
+Content of this file should be auto-generated by command `mephisto scripts local_db auto_generate_all_docs_reference_md`. Presence of this empty file is required for Docusaurus Config links to work.

docs/web/docs/reference/blueprints.md

@@ -1,108 +1,8 @@
 ---
-
 # Copyright (c) Meta Platforms and its affiliates.
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 
-sidebar_position: 3
 ---
 
-# Blueprints
-
-
-The blueprints contain all of the related code required to set up a task run.
-## parlai chat
-
-
-Tasks launched from ParlAI blueprints require the number of
-                conversations (either an int or task data for each convo), as
-                well as a world to initialize for connecting workers.  
-
-|dest|type|default|help|choices|required|
-| :--- | :--- | :--- | :--- | :--- | :--- |
-|block_qualification|str|???|Specify the name of a qualification used to soft block workers.|None|False|
-|tips_location|str|path_to_task/assets/tips.csv|Path to csv file containing tips|None|False|
-|onboarding_qualification|str|???|Specify the name of a qualification used to block workers who fail onboarding, Empty will skip onboarding.|None|False|
-|world_file|str|???|Path to file containing ParlAI world|None|True|
-|preview_source|str|???|Optional path to source HTML file to preview the task|None|False|
-|task_description_file|str|???|Path to file for the extended description of the task. Required if not providing a custom source bundle.|None|False|
-|custom_source_bundle|str|???|Optional path to a fully custom frontend bundle|None|False|
-|custom_source_dir|str|???|Optional path to a directory containing custom js code|None|False|
-|extra_source_dir|str|???|Optional path to sources that the frontend may refer to (such as images/video/css/scripts)|None|False|
-|context_csv|str|???|Optional path to csv containing task context|None|False|
-|context_jsonl|str|???|Optional path to jsonl file containing task context|None|False|
-|num_conversations|int|???|Optional count of conversations to have if no context provided|None|False|
-
-## mock
-
-
-
-
-|dest|type|default|help|choices|required|
-| :--- | :--- | :--- | :--- | :--- | :--- |
-|passed_qualification_name|str|???|Specify the name of a qualification used to designate workers who have passed screening.|None|False|
-|max_screening_units|int|???|The maximum number of screening units that can be launched with this batch, specified to limit the number of validations you may need to pay out for.|None|False|
-|use_screening_task|bool|False|Whether or not to use a screening task in this run.|None|False|
-|onboarding_qualification|str|???|Specify the name of a qualification used to block workers who fail onboarding, Empty will skip onboarding.|None|False|
-|block_qualification|str|???|Specify the name of a qualification used to soft block workers.|None|False|
-|tips_location|str|path_to_task/assets/tips.csv|Path to csv file containing tips|None|False|
-|num_assignments|int|???|How many workers you want to do each assignment|None|True|
-|use_onboarding|bool|False|Whether onboarding should be required|None|False|
-|timeout_time|int|0|Whether acts in the run assignment should have a timeout|None|False|
-|is_concurrent|bool|True|Whether to run this mock task as a concurrent task or not|None|False|
-
-## static task
-
-
-Tasks launched from static blueprints need a source html file to display to workers, as well as a csv containing values that will be inserted into templates in the html.  
-
-|dest|type|default|help|choices|required|
-| :--- | :--- | :--- | :--- | :--- | :--- |
-|block_qualification|str|???|Specify the name of a qualification used to soft block workers.|None|False|
-|tips_location|str|path_to_task/assets/tips.csv|Path to csv file containing tips|None|False|
-|onboarding_qualification|str|???|Specify the name of a qualification used to block workers who fail onboarding, Empty will skip onboarding.|None|False|
-|units_per_assignment|int|1|How many workers you want to do each assignment|None|False|
-|extra_source_dir|str|???|Optional path to sources that the HTML may refer to (such as images/video/css/scripts)|None|False|
-|data_json|str|???|Path to JSON file containing task data|None|False|
-|data_jsonl|str|???|Path to JSON-L file containing task data|None|False|
-|data_csv|str|???|Path to csv file containing task data|None|False|
-|task_source|str|???|Path to source HTML file for the task being run|None|True|
-|preview_source|unknown|???|Optional path to source HTML file to preview the task|None|False|
-|onboarding_source|unknown|???|Optional path to source HTML file to onboarding the task|None|False|
-
-## remote procedure
-
-
-Tasks launched from remote query blueprints need a
-                source html file to display to workers, as well as a csv
-                containing values that will be inserted into templates in
-                the html.  
-
-|dest|type|default|help|choices|required|
-| :--- | :--- | :--- | :--- | :--- | :--- |
-|block_qualification|str|???|Specify the name of a qualification used to soft block workers.|None|False|
-|tips_location|str|path_to_task/assets/tips.csv|Path to csv file containing tips|None|False|
-|onboarding_qualification|str|???|Specify the name of a qualification used to block workers who fail onboarding, Empty will skip onboarding.|None|False|
-|task_source|str|???|Path to file containing javascript bundle for the task|None|True|
-|link_task_source|bool|False|                Symlinks the task_source file in your development folder to the                one used for the server. Useful for local development so you can run                a watch-based build for your task_source, allowing the UI code to                update without having to restart the server each time.            |None|False|
-|units_per_assignment|int|1|How many workers you want to do each assignment|None|False|
-
-## static react task
-
-
-Tasks launched from static blueprints need
-                a prebuilt javascript bundle containing the task. We suggest building
-                with our provided useMephistoTask hook.  
-
-|dest|type|default|help|choices|required|
-| :--- | :--- | :--- | :--- | :--- | :--- |
-|block_qualification|str|???|Specify the name of a qualification used to soft block workers.|None|False|
-|tips_location|str|path_to_task/assets/tips.csv|Path to csv file containing tips|None|False|
-|onboarding_qualification|str|???|Specify the name of a qualification used to block workers who fail onboarding, Empty will skip onboarding.|None|False|
-|units_per_assignment|int|1|How many workers you want to do each assignment|None|False|
-|extra_source_dir|str|???|Optional path to sources that the HTML may refer to (such as images/video/css/scripts)|None|False|
-|data_json|str|???|Path to JSON file containing task data|None|False|
-|data_jsonl|str|???|Path to JSON-L file containing task data|None|False|
-|data_csv|str|???|Path to csv file containing task data|None|False|
-|task_source|str|???|Path to file containing javascript bundle for the task|None|True|
-|link_task_source|bool|False|                Symlinks the task_source file in your development folder to the                one used for the server. Useful for local development so you can run                a watch-based build for your task_source, allowing the UI code to                update without having to restart the server each time.            |None|False|
+Content of this file should be auto-generated by command `mephisto scripts local_db auto_generate_all_docs_reference_md`. Presence of this empty file is required for Docusaurus Config links to work.

docs/web/docs/reference/providers.md

@@ -1,39 +1,9 @@
 ---
-
 # Copyright (c) Meta Platforms and its affiliates.
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 
-sidebar_position: 4
 ---
 
-# Provider
-
-
-The crowd provider determines the source of the crowd workers.
-## mock
-
-
-
-
-|dest|type|default|help|choices|required|
-| :--- | :--- | :--- | :--- | :--- | :--- |
-|requester_name|str|???|None|None|False|
-
-## mturk
-
-
-
-
-|dest|type|default|help|choices|required|
-| :--- | :--- | :--- | :--- | :--- | :--- |
-|requester_name|str|???|None|None|False|
-
-## mturk sandbox
-
-
-
-
-|dest|type|default|help|choices|required|
-| :--- | :--- | :--- | :--- | :--- | :--- |
-|requester_name|str|???|None|None|False|
+Content of this file will be auto-generated by the command `mephisto scripts local_db auto_generate_all_docs_reference_md`.
+Presence of this file is needed for links in Docusaurus Config.

docs/web/docs/reference/requesters.md

@@ -1,46 +1,8 @@
 ---
-
 # Copyright (c) Meta Platforms and its affiliates.
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 
-sidebar_position: 5
 ---
 
-# Requesters
-
-
-The requester is an account for a crowd provider.
-
-Use `mephisto requesters` to see registered requesters, and `mephisto register <requester type>` to register.     
-## mock
-
-
-
-
-|dest|type|default|help|choices|required|
-| :--- | :--- | :--- | :--- | :--- | :--- |
-|name|str|MOCK_REQUESTER|Name for the requester in the Mephisto DB.|None|True|
-|force_fail|bool|False|Trigger a failed registration|None|False|
-
-## mturk
-
-
-AWS is required to create a new Requester. Please create an IAM user with programmatic access and AmazonMechanicalTurkFullAccess policy at https://console.aws.amazon.com/iam/ (On the "Set permissions" page, choose "Attach existing policies directly" and then select "AmazonMechanicalTurkFullAccess" policy). After creating the IAM user, you should get an Access Key ID and Secret Access Key.  
-
-|dest|type|default|help|choices|required|
-| :--- | :--- | :--- | :--- | :--- | :--- |
-|name|str|???|Name for the requester in the Mephisto DB.|None|True|
-|access_key_id|str|???|IAM Access Key ID|None|True|
-|secret_access_key|str|???|IAM Secret Access Key|None|True|
-
-## mturk sandbox
-
-
-AWS is required to create a new Requester. Please create an IAM user with programmatic access and AmazonMechanicalTurkFullAccess policy at https://console.aws.amazon.com/iam/ (On the "Set permissions" page, choose "Attach existing policies directly" and then select "AmazonMechanicalTurkFullAccess" policy). After creating the IAM user, you should get an Access Key ID and Secret Access Key.  
-
-|dest|type|default|help|choices|required|
-| :--- | :--- | :--- | :--- | :--- | :--- |
-|name|str|???|Name for the requester in the Mephisto DB.|None|True|
-|access_key_id|str|???|IAM Access Key ID|None|True|
-|secret_access_key|str|???|IAM Secret Access Key|None|True|
+Content of this file should be auto-generated by command `mephisto scripts local_db auto_generate_all_docs_reference_md`. Presence of this empty file is required for Docusaurus Config links to work.

docs/web/docs/reference/tasks.md

@@ -0,0 +1,8 @@
+---
+# Copyright (c) Meta Platforms and its affiliates.
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+---
+
+Content of this file should be auto-generated by command `mephisto scripts local_db auto_generate_all_docs_reference_md`. Presence of this empty file is required for Docusaurus Config links to work.

docs/web/docusaurus.config.js

@@ -82,7 +82,7 @@ const config = {
           },
           {
             type: "doc",
-            docId: "explanations/architecture_overview",
+            docId: "explanations/abstractions_overview",
             position: "left",
             label: "Explanations",
           },
@@ -112,7 +112,7 @@ const config = {
               },
               {
                 label: "Explanations",
-                to: "/docs/explanations/architecture_overview",
+                to: "/docs/explanations/abstractions_overview",
               },
               {
                 label: "Reference",

docs/web/static/python_api/mephisto.html

@@ -63,7 +63,7 @@ <h1 class="modulename">
 
                         <div class="docstring"><h1 id="mephisto">Mephisto</h1>
 
-<p>This is the main package directory, containing all of the core workings of Mephisto. They roughly follow the divisions noted in the <a href="https://github.com/facebookresearch/Mephisto/blob/main/docs/architecture_overview.md#agent">architecture overview doc</a>. The breakdown is as following:</p>
+<p>This is the main package directory, containing all of the core workings of Mephisto. They roughly follow the divisions noted in the <a href="https://github.com/facebookresearch/Mephisto/blob/main/docs/abstractions_overview.md#agent">abstractions overview doc</a>. The breakdown is as following:</p>
 
 <ul>
 <li><code>abstractions</code>: Contains the interface classes for the core abstractions in Mephisto, as well as implementations of those interfaces. These are the Architects, Blueprints, Crowd Providers, and Databases.</li>
@@ -289,4 +289,4 @@ <h1 class="modulename">
         }
     });
 </script></body>
-</html>
+</html>

docs/web/static/python_api/mephisto/abstractions.html

@@ -69,7 +69,7 @@ <h1 class="modulename">
 
                         <div class="docstring"><h1 id="mephisto-core-abstractions">Mephisto Core Abstractions</h1>
 
-<p>This directory contains the interfaces for the four core Mephisto abstractions (as well as subcomponents of those abstractions). Those abstractions are discussed at a high level in the <a href="https://github.com/facebookresearch/Mephisto/blob/main/docs/architecture_overview.md">architecture overvierw doc</a>.</p>
+<p>This directory contains the interfaces for the four core Mephisto abstractions (as well as subcomponents of those abstractions). Those abstractions are discussed at a high level in the <a href="https://github.com/facebookresearch/Mephisto/blob/main/docs/abstractions_overview.md">abstractions overvierw doc</a>.</p>
 
 <p>Specific implementations can be made to extend the Mephisto data model to work with new crowd providers, new task types, and new backend server architectures. These four primary abstractions are summarized below, but other sections go more in-depth.</p>
 
@@ -300,4 +300,4 @@ <h3 id="mephistodb"><code>MephistoDB</code></h3>
         }
     });
 </script></body>
-</html>
+</html>