-
Notifications
You must be signed in to change notification settings - Fork 75
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Adding tutorial stubs to docusaurus #613
Merged
Merged
Changes from 10 commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
3cc1339
Adding doc stubs
JackUrb bd3615f
Merge branch 'docusaurus' of https://github.com/facebookresearch/Meph…
JackUrb bf040eb
Contribution guide
JackUrb 45d656c
Adding documentation stubs for many sections
JackUrb 4e2dda0
Merge branch 'docusaurus' of https://github.com/facebookresearch/Meph…
JackUrb 3d2fb28
Some documentation
JackUrb 78e0143
Working through first tutorial using defaults
JackUrb 86683de
Fixing up mephisto wut
JackUrb 707fa28
Finishing first tutorial finally :)
JackUrb 3cd717a
Fixing after webpack updates, work on tutorial 2
JackUrb bb22e58
Double ii fix
JackUrb File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
label: "How to contribute" | ||
collapsed: true | ||
position: 4 |
22 changes: 22 additions & 0 deletions
22
docs/web/docs/guides/how_to_contribute/backend_development.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,22 @@ | ||
--- | ||
sidebar_position: 3 | ||
--- | ||
|
||
# Backend: dev setup | ||
|
||
We use [pre-commit](https://pre-commit.com/) to enforce code styles on the code base (using `black` for Python and `prettier` for Javascript). | ||
|
||
To setup your local codebase to auto-lint and avoid lint test failures for your PRs, please set up pre-commit for your local repo as such: | ||
|
||
1. `pip install pre-commit` | ||
2. `pre-commit install` to install git hooks | ||
3. `pre-commit run --all-files` (optional - run ad-hoc against all files) | ||
|
||
|
||
## Local development mode | ||
|
||
If you've installed Mephisto via `pip install mephisto` in the past, in order to get python to use your local version of the package, navigate to your `Mephisto` folder and run: | ||
```bash | ||
pip install -e . | ||
``` | ||
This will ensure that your local changes are used in the running version of Mephisto |
6 changes: 5 additions & 1 deletion
6
docs/web/docs/contributors/development.md → ...how_to_contribute/frontend_development.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
--- | ||
sidebar_position: 1 | ||
--- | ||
|
||
# Contributing to Mephisto | ||
|
||
Mephisto is built for developing on, but developing for Mephisto can sometimes be unclear. We aim to provide some guides on contributions for abstractions, underlying infrastructure, or developer experience, but oftentimes the best resource will be opening an issue on our Github directly. | ||
|
||
## Understanding Mephisto | ||
|
||
One of the most important parts of contributing is understanding where the project stands and where we're going. Be sure to check out relevant pages on our architecture or coming plans to ramp into things. You can also check our references when trying to dive into specific components. | ||
|
||
If documentation for a specific component is lacking here, you can take a step further to investigate the blame for the file - we strive to keep documentation for our decisions in all of our pull requests, and some insight is likely present within. | ||
|
||
## I want to help, but don't know where to start | ||
|
||
If you want to contribute with something, there are often github issues marked with [help wanted](https://github.com/facebookresearch/Mephisto/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22). We also note some as being [good first issues](https://github.com/facebookresearch/Mephisto/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22), and these often have in-depth descriptions on how to get started. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
label: "In-depth use" | ||
collapsed: true | ||
position: 3 |
3 changes: 3 additions & 0 deletions
3
docs/web/docs/guides/how_to_use/efficiency_organization/_category_.yml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
label: "Efficiency and Organization" | ||
collapsed: true | ||
position: 4 |
File renamed without changes.
3 changes: 3 additions & 0 deletions
3
docs/web/docs/guides/how-tos/docker.md → ..._to_use/efficiency_organization/docker.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
7 changes: 7 additions & 0 deletions
7
docs/web/docs/guides/how_to_use/efficiency_organization/reusing_configs.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
--- | ||
sidebar_position: 1 | ||
--- | ||
|
||
# Use the same configs across tasks | ||
|
||
TODO - talk about setting up hydra profiles |
7 changes: 7 additions & 0 deletions
7
docs/web/docs/guides/how_to_use/efficiency_organization/task_organization.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
--- | ||
sidebar_position: 2 | ||
--- | ||
|
||
# Organize tasks and qualifications | ||
|
||
TODO - extend on the workflow tutorial |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
label: "Creating a task" | ||
collapsed: false | ||
position: 2 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,28 +1,19 @@ | ||
# Front-end: FAQs | ||
--- | ||
sidebar_position: 1 | ||
--- | ||
|
||
### How do I add UI error handling for my tasks? | ||
# Developing and debugging frontends | ||
|
||
Currently, we have beta functionality for error handling. We provide a few ways of getting a signal into how your tasks are faring: | ||
|
||
1. Proactively alerting crowd workers when an error occurs and encouraging them to contact you if this happens | ||
2. Auto-logging errors for React-based tasks | ||
2. Exposing error logging infrastructure for more advanced custom front-end use cases | ||
|
||
To opt into #1 above, you need to define a global variable as such: | ||
```js | ||
window._MEPHISTO_CONFIG_ = { | ||
/* required: */ | ||
ADD_ERROR_HANDLING: true, | ||
/* optional: */ | ||
ERROR_REPORT_TO_EMAIL: "[email protected]" | ||
} | ||
``` | ||
## Adding UI error handling to tasks | ||
|
||
This will show a prompt as such if an uncaught error is detected: | ||
Currently, we have beta functionality for error handling. We provide a few ways of getting a signal into how your tasks are faring: | ||
|
||
![](/faq_ui_error_message.png) | ||
1. Auto-logging errors for React-based tasks | ||
2. Proactively alerting crowd workers when an error occurs and encouraging them to contact you if this happens | ||
3. Exposing error logging infrastructure for more advanced custom front-end use cases | ||
|
||
For #2 above, auto-logging can be enabled for React apps by importing the `<ErrorBoundary />` component and wiring it up as such: | ||
### Automatic frontend logging | ||
For #1 above, auto-logging can be enabled for React apps by importing the `<ErrorBoundary />` component and wiring it up as such: | ||
|
||
```jsx | ||
import { ErrorBoundary } from "mephisto-task"; | ||
|
@@ -35,9 +26,24 @@ return ( | |
</ErrorBoundary> | ||
); | ||
``` | ||
|
||
This will automatically send an error packet to the backend Mephisto server when an error occurs. | ||
|
||
### Alerting crowd-workers of issues | ||
To opt into #2 above, you need to define a global variable as such: | ||
```js | ||
window._MEPHISTO_CONFIG_ = { | ||
/* required: */ | ||
ADD_ERROR_HANDLING: true, | ||
/* optional: */ | ||
ERROR_REPORT_TO_EMAIL: "[email protected]" | ||
} | ||
``` | ||
|
||
This will show a prompt as such if an uncaught error is detected: | ||
|
||
![](/faq_ui_error_message.png) | ||
|
||
### Advanced Usage | ||
`handleFatalError` can also be used in any custom logic code you wish - for example, in handling errors for AJAX requests which live outside of the scope of React Error Boundaries: | ||
|
||
```jsx | ||
|
76 changes: 76 additions & 0 deletions
76
docs/web/docs/guides/how_to_use/task_creation/hosting_assets.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,76 @@ | ||
--- | ||
sidebar_position: 2 | ||
--- | ||
|
||
# Hosting task assets | ||
|
||
Generally there are two models for hosting assets related to a task, with distinct tradeoffs. These are to upload files to the routing server, or to store the files locally on Mephisto and share the data on connection. The former is generally the easier solution. | ||
|
||
|
||
### Uploading files | ||
|
||
**Pros:** | ||
- Really simple to implement with `StaticBlueprint`-based tasks. | ||
- Reduces bandwidth concerns from the main server running Mephisto, as the data is managed on the routing server. | ||
|
||
**Cons:** | ||
- Requires more storage space on the routing server. In some `Architect`s (like the `EC2Architect`), this may increase costs. In others (like the `HerokuArchitect`), it may not even be possible to exceed a maximum server size. | ||
- Data is stored on an external server, and can be directly addressed. This exposes your source data to crawling while the server is up. | ||
- Requires manual setup implementation on `Blueprint`s that don't extend the `StaticBlueprint`. | ||
|
||
The method of uploading files directly involves taking a folder and uploading its contents to the statically accessible part of the routing server. With `StaticBlueprint`s, this is done by providing an argument for `mephisto.blueprint.extra_source_dir`. For instance: | ||
|
||
```yaml | ||
# my_conf.yaml | ||
mephisto: | ||
blueprint: | ||
extra_source_dir: my_path/ | ||
... | ||
``` | ||
|
||
This would make all of the files available at `my_path/` accessible from the frontend. As such, if the file `my_path/TestImg.png` was on the local machine running mephisto, you could access `<server>/TestImg.png` from your frontend. For instance: | ||
```js | ||
function LoadedImage({source}) { | ||
... | ||
return <div> | ||
<img src={source}/> | ||
</div> | ||
} | ||
``` | ||
This component would be able to render with `<LoadedImage source={'TestImg.png'} />`. This means you can pass data for each task for the files you want it to reference in `task_data` and use these in the frontend. | ||
|
||
### Local storage of files | ||
|
||
**Pros:** | ||
- All data is stored locally, and cannot be directly compromised. | ||
- Works with any `Architect`s and `Blueprint`s. | ||
|
||
**Cons:** | ||
- Increases the size of saved data, as base64 encodings of files will be included in the final files | ||
- Reduces bandwidth for the task, as the Mephisto server is responsible for sending potentially large files | ||
|
||
This process involves sending the binary of the object to the frontend, and directly rendering it. You'd likely do this process while assembling a `task_data` array. For instance if you're working with images: | ||
```python | ||
import base64 | ||
|
||
def get_task_data(img_dir: str): | ||
imgs = {} | ||
for filename in os.listdir(img_dir): | ||
with open(os.path.join(img_dir, filename), 'rb') as bin_image: | ||
imgs[filename] = "data:image/jpeg;base64," + base64.b64encode(bin_image.read()) | ||
|
||
return [{'img_name': k, 'img_data': v} for k, v in imgs] | ||
``` | ||
|
||
Then on the frontend you can access the `img_data` and use it in a component directly. For instance: | ||
|
||
```js | ||
function PassedImage({img_data}) { | ||
... | ||
return <div> | ||
<img src={img_data}/> | ||
</div> | ||
} | ||
``` | ||
|
||
If data issues are a concern, one could modify the `AgentState` to delete the `img_data` (or other data-heavy keys) and retain filenames on the final save. |
3 changes: 3 additions & 0 deletions
3
docs/web/docs/guides/how_to_use/worker_quality/_category_.yml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
label: "Worker quality control" | ||
collapsed: false | ||
position: 3 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
9 changes: 9 additions & 0 deletions
9
docs/web/docs/guides/how_to_use/worker_quality/other_methods.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
--- | ||
sidebar_position: 5 | ||
--- | ||
|
||
# Other methods for quality control | ||
|
||
TODO discuss usage of pre-qualifications for MTurk, worker-agreement, multi-tiered worker qualifications, and review-tasks-as-tasks as methods | ||
|
||
TODO note that while these aren't yet codified, it would be great to see as a contribution. |
7 changes: 7 additions & 0 deletions
7
docs/web/docs/guides/how_to_use/worker_quality/using_golds.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
--- | ||
sidebar_position: 4 | ||
--- | ||
|
||
# Check against standards with Gold Labels | ||
|
||
TODO - guide on how to use gold labels to prevent slipping |
7 changes: 7 additions & 0 deletions
7
docs/web/docs/guides/how_to_use/worker_quality/using_onboarding.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
--- | ||
sidebar_position: 2 | ||
--- | ||
|
||
# Teach potential workers with Onboarding | ||
|
||
TODO - guide on how to use onboarding to ensure that workers are understanding their task |
7 changes: 7 additions & 0 deletions
7
docs/web/docs/guides/how_to_use/worker_quality/using_validation.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
--- | ||
sidebar_position: 3 | ||
--- | ||
|
||
# Check worker quality with Validation | ||
|
||
TODO - guide on how to use validation to ensure that the work is good automatically |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
looks like a typo, extra "i" in "onboardiing"