Skip to main content

Pyicub Repository Structure

This document describes the structure and organization of the Pyicub repository. Understanding this structure is essential for effective development, testing, deployment, and collaboration within the Pyicub project.

Table of Contents​

Overview​

The pyicub repository is structured according to industry best practices for modularity, maintainability and testability It separates source code, configuration, documentation, examples, and deployment assets into distinct directories. This modular structure ensures clear boundaries between development, deployment, documentation, and usage, facilitating efficient onboarding, robust CI/CD pipelines, and streamlined releases.

Top-Level Layout​

pyicub/
├── docker/
├── docs/
├── examples/
├── media/
├── pyicub/
├── scripts/
├── tests/
├── LICENSE
├── pytest.ini
├── README.md
├── requirements.txt
├── setup.py

Directory and File Reference​

1. docker/​

Purpose: All assets, configurations, and scripts related to containerization and deployment using Docker.

  • backend/, frontend/, local/: Contain Dockerfiles for building images for different project components or environments.
  • compose.base.yaml, compose.local.yaml, compose.yaml: Docker Compose files to orchestrate multi-container applications. Different files support multiple environments (base, local, production, etc.).
  • scripts/: Shell scripts for initializing containers, installing dependencies, configuring environments, and running tests.
  • workdir/: Provides prebuilt workspaces inside containers, organizing apps, robot configs and simulation files.

Rationale:
By segregating all containerization-related files, it is easier to maintain and extend deployment strategies without cluttering the application or core source code. This encourages reproducible environments and simplifies onboarding, CI/CD, and cloud-native deployments.

2. docs/​

Purpose: Official project documentation.

  • make.bat, Makefile: Build scripts for generating documentation (supports Sphinx and Markdown).
  • .md and .rst files: User guides, API references, usage examples, and technical documentation.
  • source/: Sphinx source files, including API docs, user guides, and static assets.
  • _autosummary/: Auto-generated API documentation using Sphinx autodoc.

Rationale:
Keeping documentation centralized ensures consistency, makes it easy to maintain, and encourages a documentation-driven development approach. It supports both developer and end-user documentation in formats familiar to the Python ecosystem.

3. examples/​

Purpose: Practical, runnable scripts demonstrating core features, usage patterns, and integration points of the Pyicub library.

  • Organized by thematic folders: YARP integration, module usage, actions, FSMs, REST API usage, controllers, etc.
  • Includes both Python scripts and associated configuration files (JSONs, images, etc.).

Rationale:
Providing hands-on examples in a dedicated folder accelerates onboarding, serves as executable documentation, and ensures that real-world scenarios are well-represented and tested.

4. media/​

Purpose: Project-related media assets.

  • pyicub-logo.png: Project logo and other visual resources.

Rationale:
Centralizing media assets avoids clutter in documentation or source folders and supports clean referencing in README files and documentation.

5. pyicub/​

Purpose: Core source code of the Pyicub library.

  • Modularized structure:
    • controllers/: Control modules (e.g., gaze, position controllers).
    • core/: Foundational utilities (logger, ports, RPC).
    • modules/: High-level robot modules (attention, camera, emotions, speech, etc.).
    • proc/: Processing tools (actionizer, FSMizer, robot API interface).
    • Other key modules: actions, fsm, helper, requests, rest, utils.

Rationale:
This organization encourages modularity, reusability, and testability. Logical grouping enables developers to quickly find and contribute to relevant components. Keeping all library code within a single package (pyicub/) is a Python best practice and facilitates distribution (e.g., via PyPI).

6. scripts/​

Purpose: For standalone helper scripts, automation, or utilities not directly tied to deployment or the main application.

Rationale:
Keeps ad-hoc tools and local utilities separate from production code and Docker assets.

7. tests/​

Purpose: Automated tests for Pyicub modules.

  • Contains unit and integration tests for core functionality (e.g., test_core.py, test_position_controller.py).
  • Can be extended to include test utilities and fixtures.

Rationale:
A dedicated test folder improves maintainability, encourages test-driven development, and integrates easily with CI systems. Tests are discoverable by default testing tools (e.g., pytest).

8. Root-Level Files​

  • README.md: Project overview, setup instructions, and quickstart.
  • requirements.txt: Python dependencies for development and production.
  • setup.py: Standard Python packaging and installation script.
  • LICENSE: Open source license.
  • pytest.ini: Configuration for the pytest test runner.

Rationale:
These files are entry points for new contributors and standardize environment setup, packaging, and licensing, ensuring compliance and developer productivity.

Rationale and Best Practices​

  • Separation of Concerns: Source code, documentation, deployment, examples, and tests are clearly separated for maintainability.
  • Docker-First Deployment: By organizing all containerization files under docker/, the project supports robust, reproducible, and portable deployments—essential for robotics projects with hardware dependencies.
  • Documentation-Driven Development: The docs/ directory supports continuous, version-controlled, and easily buildable documentation.
  • Example-Driven Learning: Comprehensive, executable examples ensure users and developers can quickly grasp and validate functionality.
  • Testing as a First-Class Citizen: A dedicated tests/ directory encourages rigorous quality control and supports continuous integration.

How to Navigate the Repository​

  • For Developers: Start with README.md for an overview. Explore pyicub/ for core code and tests/ for test examples. Use docker/ to set up a development container or read how the CI implemented.
  • For Users: Check examples/ for runnable scripts and refer to docs/ for user and API documentation.
  • For Contributors: Follow the documented coding conventions, use tests/ to validate changes, and consult development/Testing.md for testing practices.
  • For DevOps/Deployment: All relevant files are under docker/, including Compose scripts and automation utilities.

Contributions​

All contributors should follow the repository structure to ensure maintainability and scalability. When adding new modules, tests, documentation, or deployment scripts, place them in the appropriate directory as described above.