-
Notifications
You must be signed in to change notification settings - Fork 6
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Improve README and CONTRIBUTING to make the project more accessible. (#…
…632) ### Related issues - Closes #600 ### Summary - adds CONTRIBUTING.md for main repository, frontend, and backend - changes README.md for main repository, frontend, and backend - improves documentation and adds useability improvement for local usage, development, and testing. ### Checks - [ X ] All tests have passed (or issues created for failing tests) Failing frontend is known issue. --------- Co-authored-by: glass-ships <[email protected]>
- Loading branch information
1 parent
25f4d33
commit af63421
Showing
14 changed files
with
749 additions
and
253 deletions.
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| 3.10.12 |
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 @@ | ||
| # Contributor Covenant Code of Conduct | ||
|
|
||
| ## Our Pledge | ||
|
|
||
| In the interest of fostering an open and welcoming environment, we as | ||
| contributors and maintainers pledge to making participation in our project and | ||
| our community a harassment-free experience for everyone, regardless of age, body | ||
| size, disability, ethnicity, sex characteristics, gender identity and expression, | ||
| level of experience, education, socio-economic status, nationality, personal | ||
| appearance, race, religion, or sexual identity and orientation. | ||
|
|
||
| ## Our Standards | ||
|
|
||
| Examples of behavior that contributes to creating a positive environment | ||
| include: | ||
|
|
||
| * Using welcoming and inclusive language | ||
| * Being respectful of differing viewpoints and experiences | ||
| * Gracefully accepting constructive criticism | ||
| * Focusing on what is best for the community | ||
| * Showing empathy towards other community members | ||
|
|
||
| Examples of unacceptable behavior by participants include: | ||
|
|
||
| * The use of sexualized language or imagery and unwelcome sexual attention or | ||
| advances | ||
| * Trolling, insulting/derogatory comments, and personal or political attacks | ||
| * Public or private harassment | ||
| * Publishing others' private information, such as a physical or electronic | ||
| address, without explicit permission | ||
| * Other conduct which could reasonably be considered inappropriate in a | ||
| professional setting | ||
|
|
||
| ## Our Responsibilities | ||
|
|
||
| Project maintainers are responsible for clarifying the standards of acceptable | ||
| behavior and are expected to take appropriate and fair corrective action in | ||
| response to any instances of unacceptable behavior. | ||
|
|
||
| Project maintainers have the right and responsibility to remove, edit, or | ||
| reject comments, commits, code, wiki edits, issues, and other contributions | ||
| that are not aligned to this Code of Conduct, or to ban temporarily or | ||
| permanently any contributor for other behaviors that they deem inappropriate, | ||
| threatening, offensive, or harmful. | ||
|
|
||
| ## Scope | ||
|
|
||
| This Code of Conduct applies both within project spaces and in public spaces | ||
| when an individual is representing the project or its community. Examples of | ||
| representing a project or community include using an official project e-mail | ||
| address, posting via an official social media account, or acting as an appointed | ||
| representative at an online or offline event. Representation of a project may be | ||
| further defined and clarified by project maintainers. | ||
|
|
||
| ## Enforcement | ||
|
|
||
| Instances of abusive, harassing, or otherwise unacceptable behavior may be | ||
| reported by contacting the project team representative, [email protected]. All | ||
| complaints will be reviewed and investigated and will result in a response that | ||
| is deemed necessary and appropriate to the circumstances. The project team is | ||
| obligated to maintain confidentiality with regard to the reporter of an incident. | ||
| Further details of specific enforcement policies may be posted separately. | ||
|
|
||
| Project maintainers who do not follow or enforce the Code of Conduct in good | ||
| faith may face temporary or permanent repercussions as determined by other | ||
| members of the project's leadership. | ||
|
|
||
| ## Attribution | ||
|
|
||
| This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, | ||
| available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html | ||
|
|
||
| [homepage]: https://www.contributor-covenant.org | ||
|
|
||
| For answers to common questions about this code of conduct, see | ||
| https://www.contributor-covenant.org/faq |
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,109 @@ | ||
| # Welcome to the Monarch Initiative | ||
|
|
||
| The Monarch Initiative is an extensive knowledge graph and ecosystem of tools made for the benefit of clinicians, researchers, and scientists. The knowledge graph consists of millions of entities – genes, diseases, phenotypes, and many more – imported from dozens of sources. While we have a core development team, we welcome the contributions of the community to help us maintain and improve the knowledge graph and the tools that use it. | ||
|
|
||
| # Table of Contents | ||
|
|
||
| - [Useful Links](#important-links) | ||
| - [Community Guidelines](#community-guidelines) | ||
| - [Monarch App](#monarch-app) | ||
| - [Requirements](#requirements) | ||
| - [Backend Requirements](#backend-requirements) | ||
| - [Frontend Requirements](#frontend-requirements) | ||
| - [Other Requirements](#other-requirements) | ||
| - [Getting Started](#getting-started) | ||
| - [Makefile](#makefile) | ||
| - [Quick Start](#quick-start) | ||
| - [Testing and Development](#testing-and-development) | ||
| - [Backend](#backend) | ||
| - [Frontend](#frontend) | ||
| - [Deploying Monarch](#deploying-monarch) | ||
|
|
||
| # Useful Links | ||
|
|
||
| - [Monarch Documentation](https://monarch-initiative.github.io/monarch-documentation/) - In addition to the documentation here, we have a separate documentation site that is automatically generated from the codebase, which encompasses the entire Monarch Initiative ecosystem, as well as the release process and other important information. | ||
| - [Monarch Py Documentation](https://monarch-initiative.github.io/monarch-app/) - The Monarch Py documentation contains information on the Python library for interacting with the Monarch Initiative knowledge graph, as well as the FastAPI module that serves as the website's backend. | ||
| - [Monarch App Website](https://next.monarchinitiative.org/) - The Monarch Initiative website, a Vue web app using `monarch-py` as the backend. | ||
|
|
||
| # Community Guidelines | ||
|
|
||
| We welcome you to our community! We seek to provide a welcoming and safe development experience for everyone. Please read our [code of conduct](CODE_OF_CONDUCT.md) and reach out to us if you have any questions. We welcome your input! | ||
|
|
||
| # Monarch App | ||
|
|
||
| [](https://monarch-initiative.github.io/monarch-documentation/) | ||
|
|
||
| [**⭐️⭐️ View the website ⭐️⭐️**](https://next.monarchinitiative.org/) | ||
|
|
||
| The monarch-app repository is a monorepo that contains the projects necessary to build and run the web app at monarchinitiative.org and the appropriate tooling and developer resources to continue development. The frontend for the Monarch Initiative website is a javascript/typescript webapp developed using the Vue toolkit. The backend, also referred to as `monarch-py`, is a Python library for interacting with the Monarch Initiative knowledge graph. The `monarch-py` backend also includes an optional FastAPI module that serves as the website's backend and related services for enabling the frontend. | ||
|
|
||
| ## Requirements | ||
|
|
||
| The Monarch Initiative website tool chain has a few requirements that you may need to install before we are ready to work on testing or development. Here is the list of requirements and what they are used for. If you are only working on a portion of the code-base you may not need all of the tools below. | ||
|
|
||
| ### Backend Requirements | ||
|
|
||
| - Python - Most of us use Python version 3.10.12 for development and try to be compatible with versions 3.9-3.12. | ||
| - [Poetry](https://python-poetry.org/docs/#installation) - We use Poetry to manage dependencies in `monarch-py` | ||
| - [pyenv](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation) (suggested) - I recommend using pyenv to manage your Python version within different projects | ||
|
|
||
| ### Frontend Requirements | ||
|
|
||
| - [Bun](https://bun.sh/docs/installation) - Bun is used as a drop-in replacement for Node (non-browser JavaScript runtime environment) and Yarn (package manager). If you already have Node.js installed you Bun will not conflict with your Node.js environment and can be installed as a module. The frontend/CONTRIBUTING.md has simple instructions on how to install Bun. | ||
|
|
||
| ### Other Requirements | ||
|
|
||
| - Docker - Image files used for development and testing for both frontend and backend (required for Solr) | ||
| - Rust (cargo) - Required for running the semsimian server locally | ||
|
|
||
| ## Getting Started | ||
|
|
||
| To get started with development in monarch-app clone the repo and navigate to the directory. | ||
|
|
||
| ```shell | ||
| git clone [email protected]:monarch-initiative/monarch-app.git | ||
| cd monarch-app | ||
| ``` | ||
|
|
||
| In order to maintain a clean system environment you may want to create a local python environment. I also recommend setting a local python version of 3.10 with pyenv. You can do both with the following commands. | ||
|
|
||
| ```shell | ||
| pyenv install 3.10.12 | ||
| pyenv local 3.10.12 | ||
| python -m venv .venv | ||
| ``` | ||
|
|
||
| When the new virtual environment is created, you may want to do some peronal modifications to the envoronment. I edit the `activate` script to name the virtual environment more meaningfully and also install `poetry` locally (my preference, `activate` then run `pip install poetry`). After the virtual environment is set up you will want to start it before each development session by running `activate` (or in your IDE). To exit the environment run `deactivate`. | ||
|
|
||
| ### Makefile | ||
|
|
||
| The monarch-app repo uses a Makefile system to facilitate and simplify some of the development setup and deployment tasks. For detailed information on the build targets and details of implementation please refer to the [Makefile](Makefile) in the monarch-app directory. | ||
|
|
||
| ### Quick Start | ||
| For a quick-start, once the requirements above are met you can install and launch a working local version of the Monarch App with the following commands. | ||
|
|
||
| ```shell | ||
| cd monarch-app | ||
| make install | ||
| monarch solr download | ||
| monarch solr start | ||
| cd frontend | ||
| bun run dev | ||
| ``` | ||
|
|
||
| Once these commands are run you should have a working version of the Monarch App running from your local system. | ||
| _Note_: You may have to resolve some permissions issues with solr in order to download and start monarch solr. | ||
|
|
||
| # Testing and Development | ||
|
|
||
| ## Backend | ||
|
|
||
| For detailed information the backend please refer to the [README.md](./backend/README.md) and [CONTRIBUTING.md](./backend/CONTRIBUTING.md) file in the backend directory. Additional information can be find in the [documentation](https://monarch-app.monarchinitiative.org) | ||
|
|
||
| ## Frontend | ||
|
|
||
| More detailed information on frontend development and run options can be found at the [frontend README.md](./frontend/README.md) and [CONTRIBUTING.md](./frontend/CONTRIBUTING.md) files in the frontend directory. Additional information can be found in the [documentation](https://monarch-app.monarchinitiative.org) | ||
|
|
||
| # Deploying to Monarch | ||
|
|
||
| For documentation on deploying to monarch please see the [Monarch documentation](https://monarch-initiative.github.io/monarch-documentation/release-process/) regarding the release process. |
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,25 +1,26 @@ | ||
| # Monarch App | ||
| # Welcome to the Monarch Initiative | ||
|
|
||
| The Monarch Initiative is an extensive knowledge graph and ecosystem of tools made for the benefit of clinicians, researchers, and scientists. The knowledge graph consists of millions of entities – genes, diseases, phenotypes, and many more – imported from dozens of sources. | ||
|
|
||
| We welcome the contributions of the community to help us maintain and improve the knowledge graph and the tools that use it. To help get started on contributing to the Monarch Initiative, please see our CONTRIBUTING.md file. | ||
|
|
||
| [](https://monarch-initiative.github.io/monarch-app/docs) | ||
| # Monarch App | ||
| [](https://monarch-initiative.github.io/monarch-documentation/) | ||
|  | ||
|  | ||
|  | ||
|  | ||
|
|
||
| [**⭐️⭐️ View the website ⭐️⭐️**](https://next.monarchinitiative.org/) | ||
|
|
||
| This repository contains the source code for the Monarch Initiative website (a Vue webapp), | ||
| as well as `monarch-py`, a Python library for interacting with the Monarch Initiative knowledge graph, | ||
| which includes an optional FastAPI module that serves as the website's backend. | ||
| The monarch-app repo contains the source code for the Monarch Initiative website (a Vue webapp), | ||
| as well as `monarch-py`, a Python library for interacting with the Monarch Initiative knowledge graph. The `monarch-py` library also includes a FastAPI module that serves as the website's backend. Together, the frontend and backend make up the stack used to deply and run the Monarch Initiative website. | ||
|
|
||
| If you wish to run Monarch-App as a local web application, please install the requirements below and then follow on to the usage section to start the application. Refer to [Using Local Data](#using-local-data) to see how you can run the full Monarch website locally and use your own data store. | ||
|
|
||
| ### For developers | ||
|
|
||
| To get started with this repo: | ||
| ### For developers | ||
|
|
||
| ``` | ||
| git clone https://github.com/monarch-initiative/monarch-app | ||
| cd monarch-app | ||
| ``` | ||
| The monarch-app repository contains the code to run the Monarch Initiative website in the `frontend` and `backend` directories as well as documentation, helper scripts, Docker files and services to help set up a local environment for development and for deployment. | ||
|
|
||
| Then see `Makefile` or the individual `/frontend` and `/backend` folders for how you can install, develop, build, test, lint, or format the frontend or backend. | ||
| To start development, please refer to the CONTRIBUTING.md document with this README. If you are planning to only develop the frontend or backend of the application you can refer directly to the README and CONTRIBUTING files in each of those sections. |
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,37 @@ | ||
| # Welcome to the Monarch Initiative | ||
|
|
||
| The Monarch Initiative is an extensive knowledge graph and ecosystem of tools made for the benefit of clinicians, researchers, and scientists. The knowledge graph consists of millions of entities – genes, diseases, phenotypes, and many more – imported from dozens of sources. While we have a core development team, we welcome the contributions of the community to help us maintain and improve the knowledge graph and the tools that use it. | ||
|
|
||
| This CONTRIBUTING.md is for the monarch-app backend, also refered to as monarch-py, usable as either a python module or a local CLI. | ||
|
|
||
| # Useful Links | ||
|
|
||
| - [Monarch Documentation](https://monarch-initiative.github.io/monarch-documentation/) - In addition to the documentation here, we have a separate documentation site that is automatically generated from the codebase, which encompasses the entire Monarch Initiative ecosystem, as well as the release process and other important information. | ||
| - [Monarch Py Documentation](https://monarch-initiative.github.io/monarch-app/) - The Monarch Py documentation contains information on the Python library for interacting with the Monarch Initiative knowledge graph, as well as the FastAPI module that serves as the website's backend. | ||
| - [Monarch App Website](https://next.monarchinitiative.org/) - The Monarch Initiative website, a Vue web app using `monarch-py` as the backend. | ||
|
|
||
| ### Running the API: | ||
|
|
||
| #### Local development: | ||
|
|
||
| - Connect to and expose the SOLR database: | ||
| `gcloud compute ssh monarch-solr-dev -- -L 8983:localhost:8983` | ||
|
|
||
| - Start the uvicorn server: | ||
| `cd <path-to>/monarch-api && uvicorn main:app --reload` | ||
|
|
||
| #### GCP deployment: | ||
|
|
||
| - First, connect to the GCP SOLR machine: | ||
| `gcloud compute ssh monarch-api-dev -- -L 8000:localhost:8000` | ||
|
|
||
| - Then, start the uvicorn server: | ||
| `nohup uvicorn main:app --reload --host 0.0.0.0 &` | ||
|
|
||
| #### Building and using the Docker image: | ||
|
|
||
| - Build the docker image: | ||
| `docker build --rm --tag us-central1-docker.pkg.dev/monarch-initiative/monarch-api/monarch-api:{VERSION} . ` | ||
|
|
||
| - Push the docker image: | ||
| `docker push us-central1-docker.pkg.dev/monarch-initiative/monarch-api/monarch-api:{VERSION}` |
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
Oops, something went wrong.