diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..9353d87f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,96 @@ +# Contributing to foundry + +This contributor's guide is a non-exhaustive list of best practices for contributing to the foundry source code, adding a model, and/or contributing to the foundry documentation. These recommendations are a mixture of industry standards and expectations for this specific repository. + +## Table of Contents +- [Code Contributions](#code-contributions) +- [Adding a Model](#adding-a-model) +- [Documentation Contributions](#documentation-contributions) + +## Code Contributions + +### Code Organization +There is a strict dependency flow of Foundry -> [AtomWorks](https://github.com/RosettaCommons/atomworks). All models within Foundry use AtomWorks for manipulating and processing biomolecular structures, in both training and inference. + +Here is an overview of how this system is structured: +- AtomWorks: I/O, preprocessing structures, data featurization +- Foundry: Model architectures, training, inference endpoints +- `models/`: Released models that use the structure provided by Foundry and AtomWorks + +### Installing Foundry in Editable Mode +Install both foundry and models in editable mode for development: +```bash +uv pip install -e '.[all,dev]' +``` +This approach allows you to: +- Modify foundry shared utilities and see changes immediately +- Work on specific models without installing all models +- Add new models as independent packages in `models/` + +### As You Code +1. Reduce cognitive overhead: +
    +
  1. Pick meaningful, descriptive variable names.
    2. +
  2. Write docstrings and comments. All docstrings should be written using in the Google-format.
    3. +
  3. Follow PEP8 (Style Guide for Python Code) whenever possible
    4. +
  4. Follow PEP20 (The Zen of Python) whenever possible.
    5. +
+2. Write tests. Tests for the Foundry source code can be found in `foundry/tests`, tests for individual models will be in their respective directories. + ```{note} + Running tests is not currently supported, test files may be missing. + ``` + +### As You Commit +Foundry comes with a `.pre-commit-config.yaml` that runs `make format` (via `ruff format`) before each commit, enable it once per clone: +```bash +pip install pre-commit # if not already installed +pre-commit install +``` +Once it is successfully installed, it will automatically format the repo whenever you run `git commit`, but you can apply it manually via `pre-commit run --all-files`. + +Even with this, there are a few things to keep in mind to make sure your commits are easily reviewable: +1. Keep commits as “one logical unit.” This means that each commit should be a set of related changes that accomplish one task, fix one bug, or implement one feature. Using an editor like [VS Code](https://code.visualstudio.com/docs/sourcecontrol/overview) or using [GitHub Desktop](https://docs.github.com/en/desktop) can help you stage related changes together. +1. Adhere to [semantic commit conventions](https://www.conventionalcommits.org/en/v1.0.0/). +1. Submit a draft PR so people know you are working on this & can provide advice/feedback early on. + +### As you Finalize a PR +1. To make a PR merge your branch to production. The maintainers will review your PR. +1. Keep overall PR under <400 LOC (lines of code) (Rule of thumb: 500 LOC takes about 1h to review). + + +## Adding a Model +To be able to add new models as independent packages, make sure to install foundry and its models in 'editable' mode: +```bash +uv pip install -e '.[all,dev]' +``` +Once you have done this you can follow these steps to incorporate your model into the repository: +1. Create a `models/` directory with its own `pyproject.toml` +1. Add `foundry` as a dependency +1. Implement model-specific code in `models//src/` +1. Users can install this new model via `uv pip install -e ./models/` + +## Documentation Contributions +The external Foundry documentation is built using [Sphinx](https://www.sphinx-doc.org/en/master/#) and [GitHub Pages](https://docs.github.com/en/pages). + +To build the documentation you need to have the dependencies listed in `foundry/docs/docs_requirements.txt` installed, which can be easily done via +```bash +uv pip install -r docs/docs_requirements.txt +``` + +To build the documentation, navigate to the `docs` directory and run: +```bash +make html +``` +If you are new to Sphinx, please refer to the [Sphinx documentation](https://www.sphinx-doc.org/en/master/) for guidance on writing and formatting documentation. The documentation for Foundry uses MyST_parser so that documentation pages can be written in [Markdown](https://www.markdownguide.org/) or [ReStructured Text](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). + +### Organization +The `docs/source` directory contains the documentation about the Foundry source code. The `index.rst` file located here is the landing page for the documentation. + +Each model has its own `docs` folder (`foundry/models//docs`). The `foundry/docs/source/models` directory contains symlinks to these individual docs folders, this is necessary to allow Sphinx to see the model-specific documentation. If you are adding documentation for a new model, you will need to make a similar symlink: +1. Make a `docs` directory in `foundry/models/` +2. From the `foundry/docs/source/models` directory run + ```bash + ln -s ../../../models//docs + ``` + +Each of the model documentation directories have their own `index.md` file that organizes that model's documentation. \ No newline at end of file diff --git a/docs/docs_requirements.txt b/docs/docs_requirements.txt new file mode 100644 index 00000000..a6860743 --- /dev/null +++ b/docs/docs_requirements.txt @@ -0,0 +1,4 @@ +sphinx>=8.1.3 +myst-parser>=4.0.1 +sphinx-copybutton>=0.5.2 +furo>=2025.9.25 \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 6000e2d9..a34ac69e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -57,3 +57,5 @@ ".rst": "restructuredtext", ".md": "markdown", } + +suppress_warnings = ["myst.xref_missing"] diff --git a/docs/source/contributing_link.rst b/docs/source/contributing_link.rst new file mode 100644 index 00000000..90bb6fcf --- /dev/null +++ b/docs/source/contributing_link.rst @@ -0,0 +1,5 @@ +CONTRIBUTING +============ + +.. include:: ../../CONTRIBUTING.md + :parser: myst_parser.sphinx_ \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 083bb2d1..dd6fd09f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,10 +3,10 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to the official documentation for foundry +Welcome to the official documentation for Foundry ================================================= -`foundry `_ is a home for +`Foundry `_ is a home for many of the machine learning models produced by `Rosetta Commons member labs `_. .. toctree:: @@ -15,6 +15,7 @@ many of the machine learning models produced by `Rosetta Commons member labs