{"id":19974269,"url":"https://github.com/gbroques/ose-workbench-platform","last_synced_at":"2025-05-04T02:32:34.964Z","repository":{"id":38182305,"uuid":"265971477","full_name":"gbroques/ose-workbench-platform","owner":"gbroques","description":"Common platform for developing Open Source Ecology (OSE) workbenches.","archived":false,"fork":false,"pushed_at":"2022-06-10T00:23:09.000Z","size":757,"stargazers_count":6,"open_issues_count":26,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-22T21:18:12.792Z","etag":null,"topics":["freecad","freecad-workbench","opensourceecology","ose","osedev","osedev-workbench","workbench"],"latest_commit_sha":null,"homepage":"https://ose-workbench-platform.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gbroques.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-21T23:15:35.000Z","updated_at":"2023-01-17T14:26:06.000Z","dependencies_parsed_at":"2022-09-26T17:31:08.875Z","dependency_job_id":null,"html_url":"https://github.com/gbroques/ose-workbench-platform","commit_stats":null,"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbroques%2Fose-workbench-platform","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbroques%2Fose-workbench-platform/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbroques%2Fose-workbench-platform/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbroques%2Fose-workbench-platform/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gbroques","download_url":"https://codeload.github.com/gbroques/ose-workbench-platform/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252279064,"owners_count":21722831,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["freecad","freecad-workbench","opensourceecology","ose","osedev","osedev-workbench","workbench"],"created_at":"2024-11-13T03:14:29.967Z","updated_at":"2025-05-04T02:32:34.205Z","avatar_url":"https://github.com/gbroques.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OSE Workbench Platform\n[![PyPI version](https://badge.fury.io/py/ose-workbench-platform.svg)](https://badge.fury.io/py/ose-workbench-platform)\n[![Conda version](https://anaconda.org/gbroques/ose-workbench-platform/badges/version.svg)](https://anaconda.org/gbroques/ose-workbench-platform)\n[![Build Status](https://travis-ci.org/gbroques/ose-workbench-platform.svg?branch=master)](https://travis-ci.org/gbroques/ose-workbench-platform)\n[![Documentation Status](https://readthedocs.org/projects/ose-workbench-platform/badge/?version=latest)](https://ose-workbench-platform.readthedocs.io/en/latest/?badge=latest)\n[![Coverage Status](https://coveralls.io/repos/github/gbroques/ose-workbench-platform/badge.svg?branch=master)](https://coveralls.io/github/gbroques/ose-workbench-platform?branch=master)\n\n* [Introduction](#introduction)\n* [Pre-Requisites](#pre-requisites)\n* [Installation](#installation)\n* [Virtual Development Environment](#virtual-development-environment)\n* [Unit Tests](#unit-tests)\n* [Documentation](#documentation)\n* [Commands](#commands)\n  * [test](#test)\n  * [lint](#lint)\n  * [docs](#docs)\n  * [build](#build)\n  * [make](#make)\n  * [browse](#browse)\n  * [editor-config](#editor-config)\n* [Contributing](#contributing)\n* [License](#license)\n\n## Introduction\nA platform for developing workbenches for Open Source Ecology (OSE).\n\nOSE defines a \"workbench\" as a set of tools in CAD software to design and make a particular machine.\n\nEach workbench OSE develops for one of it's machines has certain common development-time or \"dev-time\" needs and dependencies.\n\nFor example, running unit tests, making documentation, and generating code to streamline workbench development.\n\nRather than duplicate the approaches to each of these needs, `ose-workbench-platform` abstracts those needs into a common platform so they aren't the concern of individual OSE workbench maintainers.\n\nEach workbench maintainer doesn't need to know or care about the particular versions and libraries we use to solve those needs, nor the particular configuration.\n\nHaving a common platform for OSE workbench development also makes it easier for developers to readily switch between workbenches by providing a common tool-set.\n\n`ose-workbench-platform` provides a command-line interface (CLI), via the `osewb` command, containing commands for common dev-time tasks such as running all tests, making documentation, initializing new workbenches, and even generating code for common tasks.\n\n## Pre-Requisites\n1. Install [Git](https://git-scm.com/)\n2. Install [Miniconda](https://docs.conda.io/en/latest/miniconda.html)\n\n## Installation\nInstall the `ose-workbench-platform` package from the `gbroques` and `conda-forge` channel in a dedicated conda environment named `osewb` (short for **O**pen **S**ource **E**cology **W**ork**B**ench) and don't ask for confirmation:\n\n    conda create --name osewb --channel gbroques --channel conda-forge --yes ose-workbench-platform\n\nActivate your new `osewb` environment:\n\n    conda activate osewb\n\nTest your installation:\n\n    osewb --help\n\nYou can deactivate this environment later by running:\n\n    conda deactivate\n\n## Virtual Development Environment\nWe use [Conda](https://docs.conda.io/projects/conda/en/latest/index.html) to create a reproducible [virtualized OSE workbench development environment](https://en.wikipedia.org/wiki/OS-level_virtualization) with requisite dependencies for development-time tasks like running FreeCAD, executing unit tests, and generating documentation from source-code comments.\n\nIn order to perform various development-time tasks for a workbench, you must first:\n\n1. Create a conda environment from the `environment.yml` file located in the root of the workbench repository\n2. Activate the environment with `conda activate \u003cenvironment name\u003e`\n\nNote, each workbench will have it's own separate environment.\n\nWorkbench environments will be named after the base package in the workbench repository (e.g. `ose3dprinter`, `osetractor`, `osepowercube`, etc.).\n\nSome common commands relating to managing environments with `conda` are documented in the below table.\n\n|Description|Command|\n|-----------|-------|\n|**Creating** the environment|`conda env create --file environment.yml`|\n|**Activating** the environment|`conda activate \u003cenvironment name\u003e`|\n|**Deactivating** the environment|`conda deactivate`|\n\nRefer to the [Conda CLI reference documentation](https://docs.conda.io/projects/conda/en/latest/commands.html) for additional information.\n\n## Unit Tests\nFor running unit tests we use [pytest](https://docs.pytest.org/en/latest/).\n\nFor test coverage, we use [coverage.py](https://coverage.readthedocs.io/en/latest/) and [pytest-cov](https://pytest-cov.readthedocs.io/en/latest/).\n\n## Documentation\nFor building documentation, we use [Sphinx](https://www.sphinx-doc.org/en/master/).\n\nFor hosting documentation, we use a free service for **open-source** projects called [Read the Docs](https://readthedocs.org/).\n\nFor a modern and mobile-friendly look, we use [Read the Docs Sphinx Theme](https://sphinx-rtd-theme.readthedocs.io/en/stable/).\n\n## Commands\nThe `osewb` command contains various sub-commands for performing common dev-time tasks of a OSE workbench.\n\n```\n$ osewb -h ↵\nusage: osewb \u003ccommand\u003e [\u003cargs\u003e]\n\nA collection commands for OSE workbench development.\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --version             show program's version number and exit\n\nCommands:\n  {test,lint,docs,make,browse,br}\n    test                Run tests in workbench\n    lint                Lint code\n    docs                Make documentation\n    make                Commands for making new code\n    browse (br)         Commands for opening documents in a web browser\n```\n\nEach sub-command may have flags and arguments, and additional information can be discovered via `osewb \u003ccommand\u003e -h` or `--help`.\n\nIs `osewb` too many characters to type? We recommend [aliasing](https://en.wikipedia.org/wiki/Alias_(command)) the ``osewb`` command as ``ose`` to reduce typing and increase speed even further.\n\nFor further convenience, any command over four characters shall include a short-alias under four characters or less. For example, `br` is the short-alias for the five-character `browse` command.\n\n### test\nOSE Workbench Platform includes a `test` command for interacting with the test-suite of a workbench.\n\n```\n$ osewb test -h ↵\nusage: osewb test\n\noptional arguments:\n  -h, --help      show this help message and exit\n  -c, --coverage  Run tests with coverage, and generate report\n```\n\nTo run the entire unit-test suite for a workbench, run:\n\n    osewb test\n\nFor running tests with coverage and generating a coverage report, pass the `-c` or `--coverage` flag to the `test` command:\n\n    osewb test --coverage\n\n### lint\nOSE Workbench Platform includes a `lint` command for linting the code of a workbench.\n\n    osewb lint\n\nThe `lint` command will:\n\n* Run `flake8` with configuration located in [.flake8](./osewb/.flake8).\n* Run `mypy` for static type checking with configuration located in [.mypy.ini](./osewb/.mypy.ini).\n\nFor automatically fixing *some* linter issues, pass the `-f` or `--fix` flag to the `lint` command:\n\n    osewb lint --fix\n\nThis will run [isort](https://github.com/timothycrosley/isort) and [autopep8](https://github.com/hhatto/autopep8) recursively on the root of the workbench repository.\n\nFor additional information, see:\n* [flake8](https://flake8.pycqa.org/en/latest/)\n* [mypy](http://www.mypy-lang.org/)\n\n### docs\nOSE Workbench Platform includes a `docs` command for building the documentation of a workbench.\n\n```\n$ osewb docs -h ↵\nusage: osewb docs [command]\n\noptional arguments:\n  -h, --help       show this help message and exit\n\nCommands:\n  {screenshot,ss}\n    screenshot (ss)\n                   Take screenshots of parts for documentation.\n```\n\nThe `docs` command will:\n\n* Remove auto-generated files such as the `_build/` and any auto-generated Sphinx sources.\n* Re-generate `docs/_build/`, `docs/\u003cbase package\u003e/`, `docs/freecad/\u003cbase package\u003e/` by running `sphinx-build . _build` within `docs/` using the Sphinx configuration specified in `docs/conf.py`\n\nFor additional information, see [sphinx-build](https://www.sphinx-doc.org/en/master/man/sphinx-build.html) and [Sphinx Configuration](https://www.sphinx-doc.org/en/master/usage/configuration.html).\n\n---\n\nAdditionally, you may pass a `screenshot` or `ss` sub-command to the `docs` command for taking screenshots of parts in a workbench:\n\n    osewb docs ss\n\nThis will look for parts in the `\u003cbase package\u003e/part` package of the current workbench, and save thumbnail screen shots in the `docs/_static/screenshot/` directory for each part.\n\n### build\nOSE Workbench Platform includes a `build` command for building a workbench.\n\n    osewb build\n\nThe `build` command aggregates the following commands into one:\n\n1. Run tests with coverage - `osewb test --coverage`\n2. Lint all code - `osewb lint`\n3. Ensure the documentation builds - `osewb docs`\n\nThe `build` command exits with `0` or `1` to pass or fail the build depending upon whether the above commands return non-zero exit codes.\n\n### make\nOSE Workbench Platform includes a `make` command for \"making\" new code.\n\n```\n$ ose make -h ↵\nusage: osewb make \u003ccommand\u003e\n\noptional arguments:\n  -h, --help            show this help message and exit\n\nCommands:\n  {workbench,wb,part,model,part-feature,pf,command}\n    workbench (wb)      Make Workbench\n    part                Make Part class\n    model               Make Model class\n    part-feature (pf)   Make Part Feature creation function\n    command             Make Command class\n```\n\n#### workbench\nNavigate to where you want to create your new workbench. Then run:\n\n    osewb make workbench \u003cmachine_display_name\u003e\n\nWhere `\u003cmachine_display_name\u003e` is the name of the machine in **Title Case**. If this contains spaces, then surround the value in double-quotes `\"\"`.\n\n```\n$ osewb make workbench Tractor ↵\nWorkbench initialized in \"ose-tractor-workbench\" directory.\n\nPerform the following commands to get started:\n\n1. Change directories and initialize the git repository:\n\n    cd ose-tractor-workbench \u0026\u0026 git init\n\n2. Create a conda environment and activate it:\n\n    conda env create --file environment.yml \u0026\u0026 conda activate osetractor\n\n3. Verify your installation:\n\n    osewb -h\n```\n\nThe above examples initializes a new workbench, in a `ose-tractor-workbench` directory, with the basic structure and files needed.\n\n```\n$ tree ose-tractor-workbench --dirsfirst ↵\nose-tractor-workbench\n├── docs\n│   ├── conf.py\n│   └── index.rst\n├── freecad\n│   └── osetractor\n│       ├── command\n│       │   ├── _add_box\n│       │   │   ├── add_box_command.py\n│       │   │   └── __init__.py\n│       │   └── __init__.py\n│       ├── icon\n│       │   ├── Box.svg\n│       │   └── __init__.py\n│       ├── init_gui.py\n│       ├── __init__.py\n│       └── OSE_Tractor.py\n├── osetractor\n│   ├── part\n│   │   ├── _box\n│   │   │   ├── box.py\n│   │   │   └── __init__.py\n│   │   └── __init__.py\n│   └── __init__.py\n├── tests\n│   ├── box_test.py\n│   └── __init__.py\n├── CONTRIBUTING.md\n├── environment.yml\n├── LICENSE\n├── MANIFEST.in\n├── README.md\n└── setup.py\n\n10 directories, 22 files\n```\n\nFor more information, see the [Pattern Catalog](https://ose-workbench-platform.readthedocs.io/en/latest/) in the docs.\n\n![OSE Tractor Workbench](./ose-tractor-workbench.png)\n\n#### part\nWithin the repository of a workbench, run the `osewb make part` command to make a new **Part Class**.\n\nFor example,\n\n    osewb make part Box\n\nMakes a new `Box` part class.\n\nFor more information, see [Part Classes](https://ose-workbench-platform.readthedocs.io/en/latest/pages/pattern_catalog/part_classes.html) in the docs.\n\n#### model\nWithin the repository of a workbench, run the `osewb make model` command to make a new **Model Class**.\n\nFor example,\n\n    osewb make model Box\n\nMakes a new `BoxModel` model class.\n\nFor more information, see [Model Classes](https://ose-workbench-platform.readthedocs.io/en/latest/pages/pattern_catalog/model_classes.html) in the docs.\n\n#### part-feature (pf)\nWithin the repository of a workbench, run the `osewb make part-feature` command to make a new **Part Feature creation function**.\n\nFor example,\n\n    osewb make part-feature my_box\n\nMakes a new `create_my_box` part feature creation function using the `MyBoxModel` class.\n\nFor more information, see [Part Feature Sub-package](https://ose-workbench-platform.readthedocs.io/en/latest/pages/pattern_catalog/workbench_package.html#part-feature-sub-package) in the docs.\n\n#### command\nWithin the repository of a workbench, run the `osewb make command` command to make a new **Command Class**.\n\nFor example,\n\n    osewb make command AddBox\n\nMakes a new `AddBoxCommand` class.\n\nFor more information, see [Command Classes](https://ose-workbench-platform.readthedocs.io/en/latest/pages/pattern_catalog/command_classes.html) in the docs.\n\n### browse\nOSE Workbench Platform includes a `browse` covenience command for opening documentation and coverage reports in a web browser.\n\n```\n$ osewb browse -h ↵\nusage: osewb browse \u003ccommand\u003e\n\noptional arguments:\n  -h, --help           show this help message and exit\n\nCommands:\n  {docs,coverage,cov}\n    docs               Opens docs in web browser\n    coverage (cov)     Opens coverage report in web browser\n```\n\nThe `docs` command opens `docs/_build/index.html` in a web browser, while `coverage` opens `htmlcov/index.html` in a web browser.\n\n### editor-config\nOSE Workbench Platform includes an `editor-config` command for outputting recommended VS Code configuration.\n\n```\n$ osewb editor-config -h ↵\nusage: osewb editor-config\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -m, --merge-workspace-settings\n                        Merge VS Code workspace settings.\n  -o, --overwrite-workspace-settings\n                        Overwrite VS Code workspace settings.\n```\n\nSimply running `osewb editor-config` will output the recommended VS Code configuration settings which user's can copy-paste into their VS Code user settings, or workspace settings, `settings.json` file(s). See [User and Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings) for additional information.\n\nThe `-m` or `--merge-workspace-settings` flag will merge the current VS workspace settings into the platform's recommended settings. The platform's settings will win any collisions or merge conflicts.\n\nThe `-o` or `--overwrite-workspace-settings` flag will overwrite the current VS Code workspace settings with either the minimal-set of recommended configuration or merged settings depending upon the presence of the `-m` flag. Before overwriting, users will see a preview of the settings and must confirm overwriting in a yes or no CLI prompt.\n\n## Contributing\nSee [Contributing Guidelines](./CONTRIBUTING.md).\n\n## License\nLicensed under the [GNU Lesser General Public License, version 2.1](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html) or LGPL v2.1. See [LICENSE](./LICENSE) for details.\n\nThis is the same license as [FreeCAD](https://wiki.freecadweb.org/Licence) to ensure this code could potentially be incorporated into future FreeCAD modules or FreeCAD source itself.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbroques%2Fose-workbench-platform","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgbroques%2Fose-workbench-platform","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbroques%2Fose-workbench-platform/lists"}