From be762f56efbaf3969dcfcbb4aa856baaad1f7204 Mon Sep 17 00:00:00 2001 From: Rachel Clune Date: Mon, 16 Feb 2026 11:33:54 -0800 Subject: [PATCH] Docs: Creating a contribution guide for Foundry I created a contribution guide for foundry that is meant to live both in the main directory and in the external documentation. Since this file lives outside of the `docs` folder but I still wanted it in the external documentation, the `contributing_link.rst` file is necessary. The content in the guide is based on the Atomworks contribution guide and some of the information provided in the Foundry README. Since this is mean to be rendered both on GitHub and Sphinx, I had to suppress Sphinx's `xref_missing` warnings because while these references are hidden in the Sphinx-built docs, they are visible in the GitHub rendered docs. While creating this file I realized that a docs_requirements.txt file needed to be created so that contributors could easily make the necessary docs environment to run Sphinx. --- CONTRIBUTING.md | 96 +++++++++++++++++++++++++++++++ docs/docs_requirements.txt | 4 ++ docs/source/conf.py | 2 + docs/source/contributing_link.rst | 5 ++ docs/source/index.rst | 5 +- 5 files changed, 110 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/docs_requirements.txt create mode 100644 docs/source/contributing_link.rst 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