docs: migrate contributor guide to MkDocs

CHANGELOG.md

@@ -26,6 +26,7 @@ Requires `compas_robots >= 1.1`.
 
 ### Changed
 
+* Migrated the contributor guide from the leftover Sphinx-era `CONTRIBUTING.rst` to a canonical Markdown guide that is also rendered in the MkDocs developer section. The setup now documents the current development commands and both ROS integration stacks.
 * Refreshed the bundled UR5 and UR10e descriptions and meshes from the official Universal Robots ROS 2 description package. All seven supported UR cells now share one `ur_description` mesh package instead of duplicating model assets per cell.
 * Bundled UR and Panda visual meshes now use their original Collada files instead of derived OBJ copies, preserving source materials and eliminating redundant converted assets. The ROS package extraction script likewise keeps downloaded DAE files unchanged.
 * The tools in `ToolLibrary` now mount along the +Z axis of their base frame instead of +X. Every planning group in `RobotCellLibrary` ends at a link whose +Z points away from the arm (`tool0` for the industrial robots, `panda_hand_tcp` for the Panda), so with this the same tool attaches to any of them with an identity attachment frame — previously each cell carried a rotation to bridge the two conventions, and a tool authored for one robot did not necessarily fit another. Their TCF states the tool's working direction with its own Z axis too, so a `TargetMode.TOOL` target aligns the tool along the target's Z — previously the TCF's X axis ran along the tool, which put every tool-mode target 90 degrees out. The tools are still modelled along +X internally and re-framed on the way out via `ToolModel.reframe_base`. The beams held by the gripper cells are authored in TCF coordinates and were re-authored to match, so they stay put. Poses are unchanged: the attached tools and workpieces of every cell land exactly where they did, only the tool's base frame is now the end effector link's frame rather than a rotated version of it. Requires the `reframe_base` support of `compas_robots >= 1.1`.

CONTRIBUTING.md

@@ -0,0 +1,104 @@
+# Contributor's Guide
+
+Contributions are welcome and greatly appreciated.
+
+## Code contributions
+
+1. Fork the [COMPAS FAB repository](https://github.com/compas-dev/compas_fab)
+   and clone your fork.
+2. Create and activate a virtual environment using `venv`, `uv`, `conda`, or
+   another environment manager.
+3. From the repository root, install the package in editable mode together
+   with its development tools:
+
+   ```bash
+   python -m pip install -e ".[dev]"
+   ```
+
+4. Run the ordinary test suite:
+
+   ```bash
+   pytest
+   ```
+
+5. For ROS integration work, start both test stacks:
+
+   ```bash
+   docker compose -f tests/integration_setup/docker-compose.yml up -d --build
+   docker compose -f tests/integration_setup/docker-compose-ros2.yml up -d --build
+   ```
+
+   Then opt into the live ROS tests and module doctests:
+
+   ```bash
+   COMPAS_FAB_RUN_ROS_INTEGRATION_TESTS=1 pytest --doctest-modules
+   ```
+
+   In PowerShell, set the environment variable first:
+
+   ```powershell
+   $env:COMPAS_FAB_RUN_ROS_INTEGRATION_TESTS = "1"
+   pytest --doctest-modules
+   ```
+
+6. Run the style checks:
+
+   ```bash
+   invoke lint
+   ```
+
+7. Add a changelog entry for user-visible behavior. Add yourself to
+   `AUTHORS.md` if this is your first contribution.
+8. Commit your changes, push your branch, and open a pull request against
+   `main`.
+
+When you finish integration testing, stop both stacks:
+
+```bash
+docker compose -f tests/integration_setup/docker-compose.yml down
+docker compose -f tests/integration_setup/docker-compose-ros2.yml down
+```
+
+## Development commands
+
+The repository uses [Invoke](https://www.pyinvoke.org/) for recurring tasks:
+
+- `invoke clean`: remove generated artifacts.
+- `invoke check`: check documentation and code consistency.
+- `invoke docs`: build the MkDocs site.
+- `invoke lint`: run code-style checks.
+- `invoke test`: run the test suite.
+- `invoke testdocs`: test examples in docstrings.
+- `invoke testcodeblocks`: test examples in documentation code blocks.
+- `invoke`: list all available tasks.
+
+## Documentation improvements
+
+Documentation source is Markdown under `docs/` and is built with
+[MkDocs](https://www.mkdocs.org/). API pages use MkDocstrings and NumPy-style
+docstrings. See the [NumPy docstring standard](https://numpydoc.readthedocs.io/en/latest/format.html)
+for examples.
+
+Build the site locally after changing documentation:
+
+```bash
+invoke docs
+```
+
+The same guide is included in the MkDocs site through
+`docs/developer/contributing.md`; keep the root file as the canonical source.
+
+## Bug reports
+
+When [reporting a bug](https://github.com/compas-dev/compas_fab/issues), include:
+
+- Operating-system name and version.
+- Python version.
+- Relevant environment and dependency details.
+- Minimal, reproducible steps and the complete error message.
+
+## Feature requests and feedback
+
+Use the [issue tracker](https://github.com/compas-dev/compas_fab/issues) for
+feature proposals and feedback. Explain the use case, describe the proposed
+behavior, and keep the initial scope as focused as practical.

MANIFEST.in

@@ -5,9 +5,9 @@ prune docs
 prune tests
 prune temp
 
-include AUTHORS.rst
+include AUTHORS.md
 include CHANGELOG.md
-include CONTRIBUTING.rst
+include CONTRIBUTING.md
 include LICENSE
 include README.md
 include requirements.txt

README.md

@@ -52,8 +52,8 @@ Start Python from the command prompt and run the following:
 ## First Steps
 
 * [Documentation](https://compas.dev/compas_fab/latest/)
-* [COMPAS FAB Examples](https://compas.dev/compas_fab/latest/examples.html)
-* [COMPAS FAB API Reference](https://compas.dev/compas_fab/latest/api.html)
+* [COMPAS FAB backend examples](https://compas.dev/compas_fab/latest/backends/)
+* [COMPAS FAB API Reference](https://compas.dev/compas_fab/latest/api/)
 * [COMPAS User Guide](https://compas.dev/compas/latest/userguide)
 * [COMPAS API Reference](https://compas.dev/compas/latest/api)
 
@@ -68,15 +68,15 @@ for questions and discussions.
 
 We love contributions!
 
-Check the [Contributor's Guide](https://github.com/compas-dev/compas_fab/blob/main/CONTRIBUTING.rst)
+Check the [Contributor's Guide](https://github.com/compas-dev/compas_fab/blob/main/CONTRIBUTING.md)
 for more details.
 
 
 ## Releasing this project
 
 Ready to release a new version of **COMPAS FAB**? Here's how to do it:
 
-* We use [semver][https://semver.org/], ie. we bump versions as follows:
+* We use [semantic versioning](https://semver.org/), i.e. we bump versions as follows:
 
   * `patch`: bugfixes.
   * `minor`: backwards-compatible features added.

docs/developer/contributing.md

@@ -0,0 +1 @@
+--8<-- "CONTRIBUTING.md"

docs/developer/index.md

@@ -3,6 +3,8 @@
 This section is for contributors extending `compas_fab` — adding a backend,
 building the Grasshopper components, or working on the internals.
 
+- **[Contributing](contributing.md)**: development installation, tests,
+  documentation, and pull-request workflow.
 - **[Backend architecture](architecture.md)**: how clients, planners and
   backend features fit together; the contract a new backend must implement.
   The API reference for the extension points lives alongside it:

mkdocs.yml

@@ -172,6 +172,7 @@ nav:
           - compas_fab.rhino: api/compas_fab.rhino.md
       - Extending compas_fab:
           - developer/index.md
+          - Contributing: developer/contributing.md
           - Backend architecture: developer/architecture.md
           - compas_fab.backends.interfaces: api/compas_fab.backends.interfaces.md
           - compas_fab.backends.ros.backend_features: api/compas_fab.backends.ros.backend_features.md