Package: ose-workbench-platform
OSE Workbench PlatformIntroductionPre-RequisitesInstallationVirtual Development EnvironmentUnit TestsDocumentationCommandstestlintdocsbuildmakebrowseeditor-configContributingLicenseIntroductionA platform for developing workbenches for Open Source Ecology (OSE).OSE defines a "workbench" as a set of tools in CAD software to design and make a particular machine.Each workbench OSE develops for one of it's machines has certain common development-time or "dev-time" needs and dependencies.For example, running unit tests, making documentation, and generating code to streamline workbench development.Rather than duplicate the approaches to each of these needs,ose-workbench-platformabstracts those needs into a common platform so they aren't the concern of individual OSE workbench maintainers.Each 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.Having a common platform for OSE workbench development also makes it easier for developers to readily switch between workbenches by providing a common tool-set.ose-workbench-platformprovides a command-line interface (CLI), via theosewbcommand, containing commands for common dev-time tasks such as running all tests, making documentation, initializing new workbenches, and even generating code for common tasks.Pre-RequisitesInstallGitInstallMinicondaInstallationInstall theose-workbench-platformpackage from thegbroqueschannel in a dedicated conda environment namedosewb(short forOpenSourceEcologyWorkBench) and don't ask for confirmation:conda create --name osewb --channel gbroques --yes ose-workbench-platformActivate your newosewbenvironment:conda activate osewbTest your installation:osewb --helpYou can deactivate this environment later by running:conda deactivateVirtual Development EnvironmentWe useCondato create a reproduciblevirtualized OSE workbench development environmentwith requisite dependencies for development-time tasks like running FreeCAD, executing unit tests, and generating documentation from source-code comments.In order to perform various development-time tasks for a workbench, you must first:Create a conda environment from theenvironment.ymlfile located in the root of the workbench repositoryActivate the environment withconda activate <environment name>Note, each workbench will have it's own separate environment.Workbench environments will be named after the base package in the workbench repository (e.g.ose3dprinter,osetractor,osepowercube, etc.).Some common commands relating to managing environments withcondaare documented in the below table.DescriptionCommandCreatingthe environmentconda env create --file environment.ymlActivatingthe environmentconda activate <environment name>Deactivatingthe environmentconda deactivateRefer to theConda CLI reference documentationfor additional information.Unit TestsFor running unit tests we usepytest.For test coverage, we usecoverage.pyandpytest-cov.DocumentationFor building documentation, we useSphinx.For hosting documentation, we use a free service foropen-sourceprojects calledRead the Docs.For a modern and mobile-friendly look, we useRead the Docs Sphinx Theme.CommandsTheosewbcommand contains various sub-commands for performing common dev-time tasks of a OSE workbench.$ osewb -h ↵
usage: osewb <command> [<args>]

A collection commands for OSE workbench development.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

Commands:
  {test,lint,docs,make,browse,br}
    test                Run tests in workbench
    lint                Lint code
    docs                Make documentation
    make                Commands for making new code
    browse (br)         Commands for opening documents in a web browserEach sub-command may have flags and arguments, and additional information can be discovered viaosewb <command> -hor--help.Isosewbtoo many characters to type? We recommendaliasingtheosewbcommand asoseto reduce typing and increase speed even further.For further convenience, any command over four characters shall include a short-alias under four characters or less. For example,bris the short-alias for the five-characterbrowsecommand.testOSE Workbench Platform includes atestcommand for interacting with the test-suite of a workbench.$ osewb test -h ↵
usage: osewb test

optional arguments:
  -h, --help      show this help message and exit
  -c, --coverage  Run tests with coverage, and generate reportTo run the entire unit-test suite for a workbench, run:osewb testFor running tests with coverage and generating a coverage report, pass the-cor--coverageflag to thetestcommand:osewb test --coveragelintOSE Workbench Platform includes alintcommand for linting the code of a workbench.osewb lintThelintcommand will:Runflake8with configuration located in.flake8.Runmypyfor static type checking with configuration located in.mypy.ini.For automatically fixingsomelinter issues, pass the-for--fixflag to thelintcommand:osewb lint --fixThis will runisortandautopep8recursively on the root of the workbench repository.For additional information, see:flake8mypydocsOSE Workbench Platform includes adocscommand for building the documentation of a workbench.$ osewb docs -h ↵
usage: osewb docs [command]

optional arguments:
  -h, --help       show this help message and exit

Commands:
  {screenshot,ss}
    screenshot (ss)
                   Take screenshots of parts for documentation.Thedocscommand will:Remove auto-generated files such as the_build/and any auto-generated Sphinx sources.Re-generatedocs/_build/,docs/<base package>/,docs/freecad/<base package>/by runningsphinx-build . _buildwithindocs/using the Sphinx configuration specified indocs/conf.pyFor additional information, seesphinx-buildandSphinx Configuration.Additionally, you may pass ascreenshotorsssub-command to thedocscommand for taking screenshots of parts in a workbench:osewb docs ssThis will look for parts in the<base package>/partpackage of the current workbench, and save thumbnail screen shots in thedocs/_static/screenshot/directory for each part.buildOSE Workbench Platform includes abuildcommand for building a workbench.osewb buildThebuildcommand aggregates the following commands into one:Run tests with coverage -osewb test --coverageLint all code -osewb lintEnsure the documentation builds -osewb docsThebuildcommand exits with0or1to pass or fail the build depending upon whether the above commands return non-zero exit codes.makeOSE Workbench Platform includes amakecommand for "making" new code.$ ose make -h ↵
usage: osewb make <command>

optional arguments:
  -h, --help            show this help message and exit

Commands:
  {workbench,wb,part,model,part-feature,pf,command}
    workbench (wb)      Make Workbench
    part                Make Part class
    model               Make Model class
    part-feature (pf)   Make Part Feature creation function
    command             Make Command classworkbenchNavigate to where you want to create your new workbench. Then run:osewb make workbench <machine_display_name>Where<machine_display_name>is the name of the machine inTitle Case. If this contains spaces, then surround the value in double-quotes"".$ osewb make workbench Tractor ↵
Workbench initialized in "ose-tractor-workbench" directory.

Perform the following commands to get started:

1. Change directories and initialize the git repository:

    cd ose-tractor-workbench && git init

2. Create a conda environment and activate it:

    conda env create --file environment.yml && conda activate osetractor

3. Verify your installation:

    osewb -hThe above examples initializes a new workbench, in aose-tractor-workbenchdirectory, with the basic structure and files needed.$ tree ose-tractor-workbench --dirsfirst ↵
ose-tractor-workbench
├── docs
│   ├── conf.py
│   └── index.rst
├── freecad
│   └── osetractor
│       ├── command
│       │   ├── _add_box
│       │   │   ├── add_box_command.py
│       │   │   └── __init__.py
│       │   └── __init__.py
│       ├── icon
│       │   ├── Box.svg
│       │   └── __init__.py
│       ├── init_gui.py
│       ├── __init__.py
│       └── OSE_Tractor.py
├── osetractor
│   ├── part
│   │   ├── _box
│   │   │   ├── box.py
│   │   │   └── __init__.py
│   │   └── __init__.py
│   └── __init__.py
├── tests
│   ├── box_test.py
│   └── __init__.py
├── CONTRIBUTING.md
├── environment.yml
├── LICENSE
├── MANIFEST.in
├── README.md
└── setup.py

10 directories, 22 filesFor more information, see thePattern Catalogin the docs.partWithin the repository of a workbench, run theosewb make partcommand to make a newPart Class.For example,osewb make part BoxMakes a newBoxpart class.For more information, seePart Classesin the docs.modelWithin the repository of a workbench, run theosewb make modelcommand to make a newModel Class.For example,osewb make model BoxMakes a newBoxModelmodel class.For more information, seeModel Classesin the docs.part-feature (pf)Within the repository of a workbench, run theosewb make part-featurecommand to make a newPart Feature creation function.For example,osewb make part-feature my_boxMakes a newcreate_my_boxpart feature creation function using theMyBoxModelclass.For more information, seePart Feature Sub-packagein the docs.commandWithin the repository of a workbench, run theosewb make commandcommand to make a newCommand Class.For example,osewb make command AddBoxMakes a newAddBoxCommandclass.For more information, seeCommand Classesin the docs.browseOSE Workbench Platform includes abrowsecovenience command for opening documentation and coverage reports in a web browser.$ osewb browse -h ↵
usage: osewb browse <command>

optional arguments:
  -h, --help           show this help message and exit

Commands:
  {docs,coverage,cov}
    docs               Opens docs in web browser
    coverage (cov)     Opens coverage report in web browserThedocscommand opensdocs/_build/index.htmlin a web browser, whilecoverageopenshtmlcov/index.htmlin a web browser.editor-configOSE Workbench Platform includes aneditor-configcommand for outputting recommended VS Code configuration.$ osewb editor-config -h ↵
usage: osewb editor-config

optional arguments:
  -h, --help            show this help message and exit
  -m, --merge-workspace-settings
                        Merge VS Code workspace settings.
  -o, --overwrite-workspace-settings
                        Overwrite VS Code workspace settings.Simply runningosewb editor-configwill output the recommended VS Code configuration settings which user's can copy-paste into their VS Code user settings, or workspace settings,settings.jsonfile(s). SeeUser and Workspace Settingsfor additional information.The-mor--merge-workspace-settingsflag will merge the current VS workspace settings into the platform's recommended settings. The platform's settings will win any collisions or merge conflicts.The-oor--overwrite-workspace-settingsflag 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-mflag. Before overwriting, users will see a preview of the settings and must confirm overwriting in a yes or no CLI prompt.ContributingSeeContributing Guidelines.LicenseLicensed under theGNU Lesser General Public License, version 2.1or LGPL v2.1. SeeLICENSEfor details.This is the same license asFreeCADto ensure this code could potentially be incorporated into future FreeCAD modules or FreeCAD source itself.