kopia lustrzana https://github.com/vilemduha/blendercam
Docs Updates, MD conversion
Rob
rodzic
743086c4d2
commit
40f08e7566
|
|
@ -48,7 +48,7 @@ Everyone puts in effort to make sure that all of **Fabex**'s features are suppor
|
|||
|
||||
It is not always possible to resolve these problems quickly, and there may be other users who are not experiencing any issues with the same feature who do not want it to be removed because someone else filed a Bug Report.
|
||||
|
||||
In these cases, a feature may be marked Experimental and, like 4+ axis operation,
|
||||
In these cases, a feature may be marked Experimental and, like 4+ axis operation, it may have to wait until a developer with the right combination of experience and equipment is available to develop, test and stabilize it.
|
||||
|
||||
## What should I do if something in **Fabex** isn't working?
|
||||
The first step is to check the docs or the chat to make sure that it is supposed to work the way you think.
|
||||
|
|
|
|||
|
|
@ -2,7 +2,6 @@
|
|||
|
||||
| Term | _(aka)_ | Description |
|
||||
|---|---|---|
|
||||
| **Toolpath Distance > Between** | Stepover | The distance between each cutting pass in Parallel operations. |
|
||||
| **Bridges** | Tabs | Small strips of material left uncut during Cutout operations to keep the workpiece in place. |
|
||||
| **Overcuts** | Fillets, Dog-Bones | Excess material that is left around corners to form slots. |
|
||||
| **Path** | Toolpath, CAMpath | |
|
||||
|
|
|
|||
|
|
@ -7,7 +7,6 @@ To use **Fabex** with **Blender** 4.1 and earlier use one of the **blendercam.zi
|
|||
```
|
||||
|
||||
## Get Blender
|
||||
|
||||
[Download Blender from the official site.](https://www.blender.org/download/)
|
||||
|
||||
```{note}
|
||||
|
|
@ -18,9 +17,7 @@ Since many distros will allow you to install Blender and Python separately this
|
|||
*For details on how to work around this issue, see the FAQ.*
|
||||
```
|
||||
## Get Fabex
|
||||
|
||||
### For Users
|
||||
|
||||
#### Stable Version
|
||||
[Download the Stable version here.](https://github.com/vilemduha/blendercam/releases)
|
||||
|
||||
|
|
@ -44,7 +41,6 @@ From the Releases page, download **fabexcnc.zip**.
|
|||
*(Don't extract it, Blender is expecting a .zip file!)*
|
||||
|
||||
#### Install Fabex
|
||||
|
||||
- Open **Blender**
|
||||
- Click **Edit** > **Preferences** > **Get Extension**
|
||||
|
||||
|
|
@ -70,4 +66,4 @@ If you intend to contribute to the **Fabex** codebase, or if you want to modify
|
|||
|
||||
For these users we recommend cloning the repository from Github, then creating a symlink (alias, shortcut) for the **'cam'** folder and moving that into [Blender's Extension directory.](https://docs.blender.org/manual/en/latest/advanced/blender_directory_layout.html)
|
||||
|
||||
For more details, see the FAQ.
|
||||
For more details, see the [FAQ](faq.md).
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Interface
|
||||
# User Interface
|
||||
|
||||
Fabex's user interface was designed to facilitate multiple different workflows, layouts and experience levels.
|
||||
|
||||
|
|
@ -11,7 +11,7 @@ Fabex can do a lot of things so we try to balance not overwhelming new users wit
|
|||
- **Experimental** - all previous options, plus those marked EXPERIMENTAL
|
||||
|
||||
**Layout** will rearrange where the panels are placed onscreen.
|
||||
- **Modern** - splits the panels between the Properties and Sidebar areas
|
||||
- **Modern** - splits the panels between the Properties and Sidebar areas
|
||||
- **Classic** - preserves the original BlenderCAM layout
|
||||
- **User** - can be edited in Preferences
|
||||
|
||||
|
|
@ -57,7 +57,7 @@ Click the **+** button to add a new Operation, or choose an Operation Preset.
|
|||
```{note}
|
||||
*If you change the object's name later on then you must also change it here. The field will turn red if the object can not be found.*
|
||||
```
|
||||
|
||||
---
|
||||
### [ Machine ]
|
||||
The **[ Machine ]** panel lets you setup your CNC machine parameters within Blender.
|
||||
|
||||
|
|
@ -73,7 +73,7 @@ You can set up your machine, then save your default file with Ctrl+U command. Th
|
|||
```{note}
|
||||
If your machine is not in the list, you can try the ISO code, which is standardized Gcode, or see the FAQ for details on writing your own Post Processor (EXPERIMENTAL!)
|
||||
```
|
||||
|
||||
---
|
||||
### [ Info ]
|
||||
The **[ Info ]** panel shows important information about your Operation.
|
||||
|
||||
|
|
@ -95,7 +95,7 @@ Failure to resolve issues with your Operation could result in damage, injury or
|
|||
|
||||
**Warnings** are there to keep you, your machine and your material safe, and we urge you to take all necessary precautions when working with CNC Machines.
|
||||
```
|
||||
|
||||
---
|
||||
### [ Operation Setup ]
|
||||
The **[ Operation Setup ]** panel gives you access to milling strategies and settings specific to those strategies.
|
||||
|
||||
|
|
@ -117,7 +117,7 @@ Depending on which **Strategy** is selected, the options will differ. Below is a
|
|||
- **Outlines**
|
||||
* **Don't Merge** - for cutout strategy. Does not merge outlines - this results into cutting in the object area! It is usefully when milling PCBs, where you don't need exact shape but need to separate areas with engraving.
|
||||
- **Bridges (Tabs)** - for cutout operation, places automatically bridges by the rules set by options that will appear after this is enabled: width, height, minimum per curve, distance.
|
||||
|
||||
---
|
||||
### [ Operation G-code ]
|
||||
The **[ Operation G-code]** panel lets you specify commands or macros to be executed at the beginning and end of Operations.
|
||||
|
||||
|
|
@ -130,7 +130,7 @@ The Gcode options in the **[ Machine ]** panel are global across all Operations,
|
|||
- **Dust Collector**
|
||||
- **Hold Down**
|
||||
- **Mist**
|
||||
|
||||
---
|
||||
### [ Optimization ]
|
||||
The **[ Optimisation ]** panel is crucial for performance.
|
||||
|
||||
|
|
@ -149,8 +149,7 @@ These settings allow you to balance performance and accuracy by limiting how man
|
|||
* **Simulation sampling raster detail** - same as sampling raster detail, but only for simulation
|
||||
* **Detail of circles used for curve offsets** - exactly what it says
|
||||
* **Use OpenCAMLib** - use external library for calculating toolpaths, improving toolpath quality (especially with waterlines) and calculation time. Has to be used with exact mode. [[Using-BlenderCAM-with-OpenCAMLib]]
|
||||
|
||||
|
||||
---
|
||||
### [ Operation Area ]
|
||||
The **[ Operation Area ]** panel controls the area where the Cutter is allowed to move and sets limits on depth and travel height.
|
||||
|
||||
|
|
@ -167,8 +166,7 @@ The **[ Operation Area ]** panel controls the area where the Cutter is allowed t
|
|||
- **Ambient** - how much space surrounding the object will be used for the milling
|
||||
- **Surfaces All** - a rectangular area will be used
|
||||
- **Surfaces Around** - object silhouette will be used, with a radius specified by Ambient radius
|
||||
|
||||
|
||||
---
|
||||
### [ Material ]
|
||||
The **[ Material ]** panel handles the size and position of your stock material - the raw material that you are planning to mill. You can enter values manually, or allow Fabex to calculate them for you based on the object you have selected.
|
||||
|
||||
|
|
@ -183,8 +181,7 @@ The **[ Material ]** panel handles the size and position of your stock material
|
|||
- **Center on Y Axis**
|
||||
- **Z Placement**
|
||||
- **Position Object** - this will move the object to positive X and Y and negative Z so that it is fully in the work area and closest to the origin.
|
||||
|
||||
|
||||
---
|
||||
### [ Movement ]
|
||||
The **[ Movement ]** panel handles how the Cutter moves during the Operation, the direction the Cutter spins, and has a little overlap with the **[ Operation Area ]** panel for the most important settings.
|
||||
|
||||
|
|
@ -204,8 +201,7 @@ The **[ Movement ]** panel handles how the Cutter moves during the Operation, th
|
|||
- **First down** - for cutout strategy. If on, the paths are cut one by one to the full depth(all layers), otherwise first all the silhouettes are cut on layer 1, then 2....
|
||||
- **Ramp Contour** - for cutout strategy, instead of going layer by layer, it goes down all the way on a ramp.
|
||||
- **Ramp Out** - also going out is performed on a ramp, to prevent burning of the finished piece by staying on one place in XY axes.
|
||||
|
||||
|
||||
---
|
||||
### [ Feedrate ]
|
||||
The **[ Feedrate ]** panel sets the Operation feedrate, Cutter speed and more.
|
||||
|
||||
|
|
@ -216,7 +212,7 @@ The **[ Feedrate ]** panel sets the Operation feedrate, Cutter speed and more.
|
|||
- **Plunge**
|
||||
- **Speed** - the feed speed gets reduced when the slope of the path is above the Plunge angle
|
||||
- **Angle** - any angle greater than the plunge angle will activate plunge speed
|
||||
|
||||
---
|
||||
### [ Cutter ]
|
||||
The **[ Cutter ]** panel allows you to select a pre-defined cutting tool, or define your own with custom Tool Number and Description.
|
||||
|
||||
|
|
@ -239,7 +235,7 @@ The **[ Cutter ]** panel allows you to select a pre-defined cutting tool, or def
|
|||
| Laser |  |
|
||||
| Custom |  |
|
||||
|
||||
|
||||
---
|
||||
### [ Chains ]
|
||||
The **[ Chains ]** panel allows you to combine multiple operations. It is useful for simulating more operations or exporting a chain of operations if you have automatic toolchanger or use the same tool for several operations.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Code Overview
|
||||
|
||||
Fabex (formerly BlenderCAM) code can be broken down into categories:
|
||||
**Fabex** *(formerly BlenderCAM)* code can be broken down into categories:
|
||||
|
||||
1. **Core Functions**
|
||||
2. **Extra Functions**
|
||||
|
|
@ -15,13 +15,14 @@ The core function of the Fabex addon is to take whatever object is in the viewpo
|
|||
These operations can be exported alone, or combined into chains to be exported and run together.
|
||||
|
||||
**Core Functions** can be found in:
|
||||
- `cam_chunk`
|
||||
- `collision`
|
||||
- `constants`
|
||||
- `exception`
|
||||
- `gcode_path`
|
||||
- `pattern`
|
||||
- `strategy`
|
||||
- `cam_chunk` - breaks paths into chunks and layers for calculation
|
||||
- `collision` - sweep collision functions for cutter tip positioning
|
||||
- `constants` - static values for precision, offsets, etc
|
||||
- `exception` - handles CAM-related exceptions
|
||||
- `gcode_import_parser` - builds toolpaths from imported Gcode files
|
||||
- `gcode_path` - builds and exports toolpaths using functions from `pattern` and `strategy`
|
||||
- `pattern` - build path patterns for various milling strategies
|
||||
- `strategy` - milling strategy function definitions - how each strategy is calculated
|
||||
|
||||
```{note}
|
||||
Although there is a file called `engine`, it is not actually part of the Core functionality, and mostly functions as a way to collect and register the UI panels that will be shown when **Fabex** is activated.
|
||||
|
|
@ -32,55 +33,111 @@ Beyond simply creating toolpaths for existing objects, Fabex can also create the
|
|||
|
||||
There are modules dedicated to creating reliefs, joinery, puzzle joinery and gears.
|
||||
|
||||
There is also a simulation module to allow a preview of what the final product will look like, as well as an asynchronous module that allows progress reports on calculations.
|
||||
There is also a simulation module to allow a preview of what the final product will look like.
|
||||
|
||||
**Extra Functions** can be found in:
|
||||
- `bas_relief`
|
||||
- `bridges`
|
||||
- `gcode_import_parser`
|
||||
- `involute_gear`
|
||||
- `joinery`
|
||||
- `pack`
|
||||
- `parametric`
|
||||
- `puzzle_joinery`
|
||||
- `simulation`
|
||||
- `slice`
|
||||
- `testing`
|
||||
- `voronoi`
|
||||
- `bas_relief` - generate a Relief mesh using Blender's Camera
|
||||
- `bridges` - generate and place Bridges / Tabs for Cutout Operations
|
||||
- `involute_gear` - generate a customizable Rack or Pinion Gear curve
|
||||
- `joinery` - create mortise, twist, finger, etc. joints
|
||||
- `pack` - arrange curves on a sheet for bulk cutting
|
||||
- `parametric` - creates curves with input functions
|
||||
- `puzzle_joinery` - create jigsaw puzzle joints
|
||||
- `simulation` - generate a mesh preview of the result of the selected toolpath
|
||||
- `slice` - cut objects into vertical slices
|
||||
- `testing` - test function definitions for the Test Suite
|
||||
- `voronoi` - generate [Voronoi](https://en.wikipedia.org/wiki/Voronoi_diagram) tesselations
|
||||
|
||||
## Utility Functions
|
||||
Utilities are generally low-level, depend only on external code (no local imports), and power both Core and Extra functions.
|
||||
Utilities are generally low-level, depend only on external code (no local imports), and power Core and Extra functions as well as some Blender-specific functionality.
|
||||
|
||||
**Utility Functions** can be found in the `utilities` folder, and have been broken down into files containing related functions.
|
||||
**Utility Functions** can be found in the `utilities/` folder, and have been broken down into files containing related functions:
|
||||
- `addon_utils` - check and load dependencies, presets, keymaps and UI
|
||||
- `async_utils` - asynchronous function for non-blocking updates
|
||||
- `bounds_utils` - get and update bounding boxes in worldspace
|
||||
- `chunk_utils` - low-level CAM chunk-related functions
|
||||
- `compare_utils` - basic comparisons - equal, overlapping etc.
|
||||
- `dict_utils` - simple Python dict functions
|
||||
- `geom_utils` - define or create simple geometry
|
||||
- `image_utils` - image creation, conversion and manipulation
|
||||
- `index_utils` - related to Indexing Operations - multi-sided jobs
|
||||
- `loop_utils` - add or remove nested loops
|
||||
- `machine_utils` - add or update the **CAM_Machine** area object
|
||||
- `material_utils` - add or update the **CAM_Material** object
|
||||
- `numba_utils` - add or bypass `numba` acceleration, if available
|
||||
- `ocl_utils` - `opencamlib` library helpers
|
||||
- `operation_utils` - add, update, sort Operations and Chains
|
||||
- `orient_utils` - add or convert Orientation objects
|
||||
- `shapely_utils` - `shapely` library helpers
|
||||
- `simple_utils` - select, delete, duplicate, rename etc.
|
||||
- `strategy_utils` - update available strategies
|
||||
- `thread_utils` - monitor threads for CAM updates
|
||||
- `version_utils` - get and set the Extension version
|
||||
|
||||
## Reference Files
|
||||
Reference files contain pre-defined data that can be quickly loaded into Blender, including Gcode Post-Processors that will translate a generic CAM toolpath into instructions specific to your CNC machine, presets for Machines, compatible cutting tools and Operations.
|
||||
|
||||
**Reference Files** can be found in the folders:
|
||||
- `post_processors`
|
||||
- `presets`
|
||||
- `tests`
|
||||
- `post_processors/` - all currently available Gcode Post-Processors
|
||||
- `presets/` - Machine, Cutter, Operation preset files
|
||||
- `tests/` - an automated suite to ensure consistent calculations and output
|
||||
|
||||
And the files:
|
||||
- `testing`
|
||||
- `version`
|
||||
- `testing` - test function definitions
|
||||
- `version` - Extension version
|
||||
|
||||
## Blender Files
|
||||
All the functionality and data listed above needs to be connecetd to Blender.
|
||||
|
||||
This is done by registering PropertyGroups that contain all the data for our CNC machine, and Operations, passing that to Operators that can calculate that data, and exposing those Operators as buttons and controls in the User Interface.
|
||||
|
||||
**Blender Files** can be found in the folders:
|
||||
- `properties/`
|
||||
- `operators/`
|
||||
- `ui/`
|
||||
|
||||
And also include the `blender_manifest.toml` file, which defines the Extension name, author(s), website, license, tags, wheels etc, and is read by **Blender** when you install **Fabex**.
|
||||
|
||||
### Properties
|
||||
Properties allow you to store data in your Blender Scene or Object.
|
||||
- `chain_props` - CAM Chain-related data
|
||||
- `info_props` - Info Panel data, like Estimates
|
||||
- `interface_props` - UI Layout data and callback functions
|
||||
- `machine_props` - Machine Panel data - your CNC Machine settings
|
||||
- `material_props` - Stock material-related settings
|
||||
- `movement_props` - Movement Panel data, like Climb vs Conventional cut
|
||||
- `operation_props` - all Operation data not covered elsewhere
|
||||
- `optimisation_props` - Optimisation Panel data, like Path Point reduction
|
||||
|
||||
### Operators
|
||||
Python functions need to be wrapped in a Blender Operator to be stored and called in Blender.
|
||||
- `async_op` - asynchronous Operator Mixin class for non-blocking updates
|
||||
- `bas_relief_ops` - create a Bas Relief mesh from a Blender Camera
|
||||
- `bridges_op` - generate and place Bridges / Tabs for Cutout Operations
|
||||
- `chain_ops` - add, remove, sort CAM Chains
|
||||
- `curve_create_ops` - add Sign Plate, Drawer, Mortise, Interlock, Puzzle Joint, Gear objects
|
||||
- `curve_equation_ops`- add Periodic, Lissajous, Hypotrochoid and Custom Curve objects
|
||||
- `curve_tools_ops` - Boolean, Convex Hull, Intarsion, Overcuts, Remove Doubles, and Pocket Surfaces
|
||||
- `gcode_import_op` - creates a toolpath object from an imported Gcode file
|
||||
- `orient_op` - add Orientation object
|
||||
- `pack_op` - pack curves on sheet
|
||||
- `path_ops` - create, chain, calculate, export toolpaths
|
||||
- `position_op` - position Stock material within Machine Work Area
|
||||
- `preset_ops` - execute Preset files
|
||||
- `simulation_ops` - simulate the selected toolpath
|
||||
- `slice_op` - slice the selected object into a series of curves
|
||||
|
||||
### User Interface
|
||||
Files related to Blender's UI - panels, menus, pie menus, popup dialogs etc.
|
||||
|
||||
**Blender Files** can be found in the `operators`, `properties` and `ui` folders, as well as the `blender_manifest.toml` file.
|
||||
Files related to Blender's User Interface (aka UI) are found in the `ui` folder, which has been broken down into sub-folders for easier management:
|
||||
- `icons/` - custom .png icon images
|
||||
- `menus/` - the **Fabex CNC** menu in the 3D viewport, and its children
|
||||
- `panels/` - the main **Fabex** interface
|
||||
- `pie_menu/` - the Pie Menu system, called with `Alt+C`
|
||||
|
||||
## Dependencies
|
||||
Python wheels - executable binaries packed in for all supported systems.
|
||||
- `opencamlib`
|
||||
- `shapely`
|
||||
|
||||
```{note}
|
||||
The wheels are for Python version 3.11, and will not work with other Python versions
|
||||
|
|
|
|||
|
|
@ -0,0 +1,36 @@
|
|||
# Style Guide
|
||||
|
||||
As a **Blender** extension, **Fabex** follows the guidelines laid out by the **Blender Foundation**:
|
||||
|
||||
[Blender Code Best Practices](https://docs.blender.org/api/current/info_best_practice.html)
|
||||
|
||||
[Extension Guidelines](https://docs.blender.org/manual/en/latest/advanced/extensions/getting_started.html#how-to-create-extensions)
|
||||
|
||||
In short, **Blender** uses a modified version of the [pep8](https://peps.python.org/pep-0008/) standard, meaning:
|
||||
|
||||
- Classes are `NamedLikeThis` - no spaces, all words capitalized
|
||||
- Functions, modules, variables, etc are `named_like_this` - spaces replaced with underscores, no capital letters
|
||||
- No `*` imports - e.g. `from module import *` should be rewritten to specify exactly what is being imported - `from module import Class, function, variable as other_name` etc.
|
||||
|
||||
**Fabex** extends the default line-length to 100 to allow some of the longer equations to remain on a single line.
|
||||
|
||||
An auto-formatter, **Black**, has been implemented to ensure code consistency across contributions.
|
||||
It will ensure that your spacing, indentation etc are in line with the project guidelines.
|
||||
|
||||
Most Code Editors/IDEs are able to integrate the **Black** formatter, so you can format your code while you work.
|
||||
|
||||
## Project Structure
|
||||
|
||||
**Fabex** is a huge addon, with many different functions, added by many different contributors over the course of 12 years of development!
|
||||
|
||||
In order to avoid conflicts, bugs and import errors a hierarchy has been established:
|
||||
|
||||
- First, `utilities` are at the lowest level - they depend on external libraries (e.g.: `bpy`, `shapely`, `numpy` etc) and are used to power the other classes and functions
|
||||
- Second, are all the files in the main addon folder (e.g.: `cam_chunk`, `gcode_path`, `strategy`) and they use external libraries, as well as `utilities` to power Blender's functions
|
||||
- Third, `properties`, `operators` and `ui` are **Blender** classes that use `utilites` and the main files to integrate **Fabex** functions into **Blender**
|
||||
|
||||
The rest of the files can be considered references:
|
||||
|
||||
- `post_processors` and `presets` will be loaded based on user selections in **Blender**
|
||||
- `tests` contains automated testing functions related to Github Workflows (see the Testing page for more details)
|
||||
- `wheels` conatins the pre-built Python binaries that power the external dependencies `shapely` and `opencamlib` - they are loaded automatically by **Blender**
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
Style Guide
|
||||
===========
|
||||
As a Blender extension, Fabex follows the guidelines laid out by the Blender Foundation:
|
||||
|
||||
`Blender Code Best Practices <https://docs.blender.org/api/current/info_best_practice.html>`_
|
||||
|
||||
`Extension Guidelines <https://docs.blender.org/manual/en/latest/advanced/extensions/getting_started.html#how-to-create-extensions>`_
|
||||
|
||||
In short, Blender uses a modified version of the `pep8 <https://peps.python.org/pep-0008/>`_ standard, meaning:
|
||||
|
||||
- Classes are ``NamedLikeThis`` - no spaces, all words capitalized
|
||||
- Functions, modules, variables, etc are ``named_like_this`` - spaces replaced with underscores, no capital letters
|
||||
- No ``*`` imports - e.g. ``from module import *`` should be rewritten to specify exactly what is being imported - ``from module import Class, function, variable as other_name`` etc.
|
||||
|
||||
Fabex extends the default line-length to 100 to allow some of the longer equations to remain on a single line.
|
||||
|
||||
An auto-formatter, Black, has been implemented to ensure code consistency across contributions.
|
||||
It will ensure that your spacing, indentation etc are in line with the project guidelines.
|
||||
|
||||
Most Code Editors/IDEs are able to integrate the Black formatter, so you can format your code while you work.
|
||||
|
||||
Project Structure
|
||||
******************
|
||||
Fabex is a huge addon, with many different functions, added by many different contributors over the course of 12 years of development!
|
||||
|
||||
In order to avoid conflicts, bugs and import errors a hierarchy has been established:
|
||||
|
||||
- First, ``utilities`` are at the lowest level - they depend on external libraries (e.g.: ``bpy``, ``shapely``, ``numpy`` etc) and are used to power the other classes and functions
|
||||
- Second, are all the files in the main addon folder (e.g.: ``cam_chunk``, ``gcode_path``, ``strategy``) and they use external libraries, as well as ``utilities`` to power Blender's functions
|
||||
- Third, ``properties``, ``operators`` and ``ui`` are Blender classes that use ``utilites`` and the main files to integrate Fabex functions into Blender
|
||||
|
||||
The rest of the files can be considered references:
|
||||
|
||||
- ``post_processors`` and ``presets`` will be loaded based on user selections in Blender
|
||||
- ``tests`` contains automated testing functions related to Github Workflows (see the Testing page for more details)
|
||||
- ``wheels`` conatins the pre-built Python binaries that power the external dependencies ``shapely`` and ``opencamlib`` - they are loaded automatically by Blender
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
Test Suite
|
||||
===========
|
||||
# Test Suite
|
||||
|
||||
The Test Suite is an automated testing tool that helps ensure that the addon functionality is not impacted by future code contributions.
|
||||
|
||||
The ``tests`` folder contains a ``TESTING_PROCEDURE`` file that describes how to run the Test Suite locally, or add your own tests to it.
|
||||
The `tests` folder contains a `TESTING_PROCEDURE` file that describes how to run the Test Suite locally, or add your own tests to it.
|
||||
|
||||
It runs a series of pre-defined operations, outputs gcode files that can be compared against reference gcode files to ensure that the results are the same.
|
||||
|
||||
|
|
@ -10,4 +10,4 @@ Most users will not need to run, access or change any part of the Test Suite, bu
|
|||
|
||||
With an addon as large and varied as Fabex, it can be easy to accidentally break something that seems unrelated to what you are working on, and the Test Suite will help to point those issues out.
|
||||
|
||||
(see the Workflows page for more details)
|
||||
*(see the [Workflows](workflows.md) page for more details)*
|
||||
|
|
@ -0,0 +1,55 @@
|
|||
# Workflows & Actions
|
||||
|
||||
Fabex uses a system called Github Actions to automatically perform a series of tasks:
|
||||
|
||||
- Building and Testing the latest code changes
|
||||
- Creating New Releases with updated version numbers
|
||||
- Building a Documentation website based on docstrings in the code
|
||||
- Formatting code submissions with the Black formatter
|
||||
|
||||
In the root folder of the repository, there is a folder called `.github`, and inside that is a folder called `workflows`.
|
||||
|
||||
This folder contains a series of `.yaml` or `.yml` (either will work) files that describe what will trigger the workflow to start (e.g.: push, pull request etc), and which workflow file to run (e.g.: `build_and_test.yaml`)
|
||||
|
||||
## Build and Test
|
||||
|
||||
`build_and_test.yaml` allows you to specify which version of Blender to build and test against, along with various other options.
|
||||
|
||||
It will be triggered by a push or pull request and it will then:
|
||||
|
||||
- checkout the repository and create the addon file
|
||||
- either download a new version of Blender, or restore the version downloaded from the previous workflow run
|
||||
- install the addon and run the Test Suite
|
||||
- upload the addon file that it created along with a log of the test results
|
||||
|
||||
## Create New Release
|
||||
|
||||
`create_release.yaml` allows you to specify the addon version that you want to create.
|
||||
|
||||
The maintainer can decide whether the changes constitute a MAJOR, MINOR or PATCH release (e.g.: `v1.5.12`):
|
||||
|
||||
- MAJOR - usually means many breaking changes - the **`1`** in `1.5.12`
|
||||
- MINOR - a new feature, or changes that won't break compatibility with previous version - the **`.5`** in `1.5.12`
|
||||
- PATCH - a typo, or bugfix - the **`.12`** in `1.5.12`
|
||||
|
||||
## Black Formatter
|
||||
|
||||
`black.yml` will format code submissions on pull request according to the configuration laid out in thhe `pyproject.toml` file.
|
||||
|
||||
Other than extending the line length to 100 characters, the default Black config is unchanged.
|
||||
|
||||
## Docs Pages
|
||||
|
||||
`docs_pages.yml` will build a complete documentation website based on the files in the `docs` folder.
|
||||
|
||||
Using the sphinx/Google docstring format allow this action to pull comments out of the code, and format them the same way as the **Blender** or `shapely` docs.
|
||||
|
||||
This helps ensure that any changes made to the code are also made to the documentation, to avoid situations where a programmer has renamed a function or Class in the code, but forgotten to update the docs.
|
||||
|
||||
In order for this system to work, docstrings have to follow a specific format: [Google Style Python Docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
|
||||
|
||||
|
||||
|
||||
``{note}
|
||||
Although the addon uses Sphinx to build the docs, it was decided that Google-style strings would be used in the code for readability, that would then be converted automatically to Sphinx format using the Napoleon extension.
|
||||
``
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
Workflows & Actions
|
||||
===================
|
||||
Fabex uses a system called Github Actions to automatically perform a series of tasks:
|
||||
|
||||
- Building and Testing the latest code changes
|
||||
- Creating New Releases with updated version numbers
|
||||
- Building a Documentation website based on docstrings in the code
|
||||
- Formatting code submissions with the Black formatter
|
||||
|
||||
In the root folder of the repository, there is a folder called ``.github``, and inside that is a folder called ``workflows``.
|
||||
|
||||
This folder contains a series of ``.yaml`` or ``.yml`` (either will work) files that describe what will trigger the workflow to start (e.g.: push, pull request etc), and which workflow file to run (e.g.: ``build_and_test.yaml``)
|
||||
|
||||
Build and Test
|
||||
****************
|
||||
``build_and_test.yaml`` allows you to specify which version of Blender to build and test against, along with various other options.
|
||||
|
||||
It will be triggered by a push or pull request and it will then:
|
||||
|
||||
- checkout the repository and create the addon file
|
||||
- either download a new version of Blender, or restore the version downloaded from the previous workflow run
|
||||
- install the addon and run the Test Suite
|
||||
- upload the addon file that it created along with a log of the test results
|
||||
|
||||
Create New Release
|
||||
********************
|
||||
``create_release.yaml`` allows you to specify the addon version that you want to create.
|
||||
|
||||
The maintainer can decide whether the changes constitute a MAJOR, MINOR or PATCH release (e.g.: ``v1.5.12``):
|
||||
|
||||
- MAJOR - usually means many breaking changes - the ``1`` in ``v1.5.12``
|
||||
- MINOR - a new feature, or changes that won't break compatibility with previous version - the ``.5`` in ``1.5.12``
|
||||
- PATCH - a typo, or bugfix - the ``.12`` in ``1.5.12``
|
||||
|
||||
Docs Pages
|
||||
***********
|
||||
``docs_pages.yml`` will build a complete documentation website based on the files in the ``docs`` folder.
|
||||
|
||||
Using the sphinx/Google docstring format allow this action to pull comments out of the code, and format them the same way as the Blender or Shapely docs.
|
||||
This helps ensure that any changes made to the code are also made to the documentation, which helps avoid situations where a programmer has renamed a function or Class in the code, but forgotten to update the docs.
|
||||
|
||||
In order for this system to work, docstrings have to follow a specific format: `Google Style Python Docstrings <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`_
|
||||
|
||||
NOTE: Although the addon uses Sphinx to build the docs, it was decided that Google-style strings would be used in the code for readability, that would then be converted automatically to Sphinx format using the Napoleon extension.
|
||||
Ładowanie…
Reference in New Issue