From 30b50644ce2c45f1fddae921cf4ae1d27e28a7b4 Mon Sep 17 00:00:00 2001 From: Gonzalo Casas Date: Thu, 27 Aug 2026 14:30:32 +0200 Subject: [PATCH] docs: migrate contributor guide to MkDocs --- CHANGELOG.md | 1 + CONTRIBUTING.md | 104 ++++++++++++++++++++++++++++++ CONTRIBUTING.rst | 113 --------------------------------- MANIFEST.in | 4 +- README.md | 8 +-- docs/developer/contributing.md | 1 + docs/developer/index.md | 2 + mkdocs.yml | 1 + 8 files changed, 115 insertions(+), 119 deletions(-) create mode 100644 CONTRIBUTING.md delete mode 100644 CONTRIBUTING.rst create mode 100644 docs/developer/contributing.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 4081a5ccf7..e7ead23dd2 100644 --- a/CHANGELOG.md +++ b/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`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..556f4c0f1d --- /dev/null +++ b/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. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index 0fac6aee01..0000000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,113 +0,0 @@ -.. _contributors_guide: - -Contributor's Guide -=================== - -Contributions are always welcome and greatly appreciated! - -Code contributions ------------------- - -We love pull requests from everyone! Here's a quick guide to improve the code: - -1. Fork `the repository `_ and clone the fork. -2. Create a virtual environment using your tool of choice (e.g. ``virtualenv``, ``conda``, etc). -3. Install development dependencies: - -:: - - pip install -r requirements-dev.txt - -4. From the `compas_fab` directory, run the docker containers: - -:: - - docker compose -f "tests/integration_setup/docker-compose.yml" up -d --build - -5. Make sure all tests pass: - -:: - - invoke test --doctest --codeblock - -6. Start making your changes to the **main** branch (or branch off of it). -7. Make sure all tests still pass: - -:: - - invoke test --doctest --codeblock - -8. From the `compas_fab` directory, stop the docker containers: - -:: - - docker compose -f "tests/integration_setup/docker-compose.yml" down - -9. Check there are no linter errors: - -:: - - invoke lint - -10. Add yourself to ``AUTHORS.rst``. -11. Commit your changes and push your branch to GitHub. -12. Create a `pull request `_ through the GitHub website. - - -During development, use `pyinvoke `_ tasks on the -command prompt to ease recurring operations: - -* ``invoke clean``: Clean all generated artifacts. -* ``invoke check``: Run various code and documentation style checks. -* ``invoke docs``: Generate documentation. -* ``invoke lint``: Run code linter for coding style checks. -* ``invoke test``: Run all tests and checks in one swift command. -* ``invoke``: Show available tasks. - - -Documentation improvements --------------------------- - -We could always use more documentation, whether as part of the -introduction/examples/usage documentation or API documentation in docstrings. - -Documentation is written in `reStructuredText `_ -and use `Sphinx `_ to generate the HTML output. - -The project uses Numpy style docstrings, see -`Sphinx extension Napoleon's documentation `_ -for examples. - -Once you made the documentation changes locally, run the documentation generation:: - - invoke docs - - -Bug reports ------------ - -When `reporting a bug `_ -please include: - -* Operating system name and version. -* Python version. -* Any details about your local setup that might be helpful in troubleshooting. -* Detailed steps to reproduce the bug. - -Feature requests and feedback ------------------------------ - -The best way to send feedback is to file an issue on -`Github `_. If you are proposing a feature: - -* Explain in detail how it would work. -* Keep the scope as narrow as possible, to make it easier to implement. - -Design documents ----------------- - -.. toctree:: - :maxdepth: 1 - :glob: - - developer/* diff --git a/MANIFEST.in b/MANIFEST.in index 3594f73eb0..920b37058e 100644 --- a/MANIFEST.in +++ b/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 diff --git a/README.md b/README.md index cb4237f542..a1e701ce42 100644 --- a/README.md +++ b/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,7 +68,7 @@ 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. @@ -76,7 +76,7 @@ for more details. 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. diff --git a/docs/developer/contributing.md b/docs/developer/contributing.md new file mode 100644 index 0000000000..ea38c9bff4 --- /dev/null +++ b/docs/developer/contributing.md @@ -0,0 +1 @@ +--8<-- "CONTRIBUTING.md" diff --git a/docs/developer/index.md b/docs/developer/index.md index 8d980c1b09..1871d03b2b 100644 --- a/docs/developer/index.md +++ b/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: diff --git a/mkdocs.yml b/mkdocs.yml index 362aa462f4..6ff6e418be 100644 --- a/mkdocs.yml +++ b/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