Docs: Creating a contribution guide for Foundry

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/<model>`: 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:
+    <ol type="a">
+        <li>Pick meaningful, descriptive variable names.</li>
+        <li>Write docstrings and comments. All docstrings should be written using in the <a href=https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html>Google-format</a>.</li>
+        <li>Follow <a href=https://peps.python.org/pep-0008/>PEP8 (Style Guide for Python Code)</a> whenever possible</li>
+        <li>Follow <a href=https://peps.python.org/pep-0020/>PEP20 (The Zen of Python)</a> whenever possible.</li>
+    </ol>
+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/<model_name>` directory with its own `pyproject.toml`
+1. Add `foundry` as a dependency
+1. Implement model-specific code in `models/<model-name>/src/`
+1. Users can install this new model via `uv pip install -e ./models/<model_name>`
+
+## 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/<model_name>/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/<model_name>`
+2. From the `foundry/docs/source/models` directory run
+    ```bash
+    ln -s ../../../models/<model_name>/docs <model_name>
+    ```
+
+Each of the model documentation directories have their own `index.md` file that organizes that model's documentation. 

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

docs/source/conf.py

@@ -57,3 +57,5 @@
     ".rst": "restructuredtext",
     ".md": "markdown",
     }
+
+suppress_warnings = ["myst.xref_missing"]

docs/source/contributing_link.rst

@@ -0,0 +1,5 @@
+CONTRIBUTING
+============
+
+.. include:: ../../CONTRIBUTING.md
+   :parser: myst_parser.sphinx_

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 <https://github.com/RosettaCommons/foundry/tree/production>`_ is a home for
+`Foundry <https://github.com/RosettaCommons/foundry/tree/production>`_ is a home for
 many of the machine learning models produced by `Rosetta Commons member labs <https://rosettacommons.org/about/labs/>`_. 
 
 .. toctree::
@@ -15,6 +15,7 @@ many of the machine learning models produced by `Rosetta Commons member labs <ht
 
    license_link.rst
    installation_faq.md
+   contributing_link.rst
 
 .. toctree::
    :maxdepth: 1