| Name | sca2d JSON |
| Version |
0.3.1
JSON |
| download |
| home_page | None |
| Summary | A static code analyser for OpenSCAD. |
| upload_time | 2025-08-10 22:25:42 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
linting
openscad
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# SCA2D - Static Code Analysis for SCAD
{width=50%}
This is a linter for OpenSCAD. The focus is to properly lex the `.scad` files so that we can test for dangerous code like redefining variable from other scopes.
SCA2D has been used for a few years now by the OpenFlexure Microscope project, but may have issue with projects that use different conventions.
It can:
* Parse any `.scad` file. We don't yet do extensive testing. Please raise an issue if you find a parsing error in SCA2D.
* Parse included and used `.scad` files and checking variable, function, and module usage in different scopes.
* Report for a number of code errors, code style issues, and some whitespace issues.
SCA2D is also experimenting with creating documentation while linting.
## How to install
If you have Python 3.6 or later installed on your machine (and on the PATH) you can install SCA2D from PyPi by running the following command from a terminal
pip install sca2d
to upgrade your current versions of SCA2D run:
pip install sca2d --upgrade
You can check that SCA2D is installed by running the following:
sca2d -h
you should see a help screen.
### Install issues
If you have problems with installation possible problems include:
* You may need to run `pip3` instead of `pip`
* Python may not be on the PATH, this often happens in Windows depending on how python was installed
## How to run
To analyse a `.scad` file run:
sca2d filename.scad
This will print any code messages to the screen.
To analyse all `.scad` files in a directory run:
sca2d dir_path
This will also print any code messages to the screen.
**To also generate documentation run.**
sca2d --docs dir_path.
Additionally the `--project` option can be used to set a project name for the documentation.
If you wish to inspect the parse tree that SCA2D generates and then uses you can instead run:
sca2d --output-tree filename.scad
the tree will be printed into a file called `filename.sca2d`.
### SCA2D Docstring Conventions for OpenSCAD
To enable automatic documentation parsing and example image generation, SCA2D defines a simple docstring format for OpenSCAD code. These conventions are enforced and utilised by the SCA2D documentation tooling.
- Use `/* */`-style C comments for docstrings.
- Do **not** include leading `*`s on each line.
- Document parameters using Python-style directives:
- `:param arg1: Description of the argument`
- `:return:` or `:returns:` to describe return values
- `:assert condition:` to describe assertions or expected conditions (in place of `:raises:`)
- Multiline descriptions (for `:param`, `:return:`, or `:assert`) should indent subsequent lines by **4 spaces**.
- All other content is treated as **Markdown**.
- Use fenced code blocks (` ``` `) for examples or inline code.
#### Docstring Example
```scad
/* Create a box with optional bevelled edges.
:param size: A 2D vector specifying the width and height
:param bevel: Optional bevel radius (default 0)
:return: A 2D shape representing the box
*/
module box(size, bevel = 0) {
// ...
}
```
#### Rendering images for examples
To include a rendered image of an example use a fenced code block that begins with ` ```example `. This blocks trigger automatic image generation as part of the documentation build.
Customisation is currently fairly limited.
* To set the camera angle use the special scad variables (`$vpt`, `$vpr`, and `$vpd`) in your example.
* By default preview mode is used to use render mode add the word `render` after `example`: ` ```example render`
* By images have the axes showing, add `no-axes` after `example` to suppress rendering axes: ` ```example no-axes`
#### Other Options for Documenting OpenSCAD
Projects like [`openscad_docsgen`](https://https://github.com/BelfrySCAD/openscad_docsgen) also generate OpenSCAD docs.
We did consider following the same conventions, however, because `openscad_docsgen` does not parse the SCAD code, their conventions include a lot of repetition of information found in the code (such as function/module signatures). The format also contains a fairly rigid structure to the documentation, prevent simply adding docs as you go to specific functions.
The SCA2D approach is to parse the SCAD source first, to automatically create module and function signatures, so documentation can focus purely on usage, behaviour, and intent. This avoids redundancy, reduces maintenance overhead, and allows for lightweight Markdown-based docstrings that feel familiar to developers coming from Python or similar languages.
At the time of writing `openscad_docsgen` is more mature than SCA2D's documentation tooling, and has more options for generating example images.
## How to get involved with SCA2D
The best way to get involved is to find bugs and then [open an issue](https://gitlab.com/bath_open_instrumentation_group/sca2d/-/issues). You could also make changes and open a merge request.
Raw data
{
"_id": null,
"home_page": null,
"name": "sca2d",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "Linting, OpenSCAD",
"author": null,
"author_email": "Julian Stirling <julian@julianstirling.co.uk>",
"download_url": "https://files.pythonhosted.org/packages/0b/7b/defe4edbabaf47c4af5663bdda49ff9016678b26f9c77d302424be08cde0/sca2d-0.3.1.tar.gz",
"platform": null,
"description": "# SCA2D - Static Code Analysis for SCAD\n\n{width=50%}\n\nThis is a linter for OpenSCAD. The focus is to properly lex the `.scad` files so that we can test for dangerous code like redefining variable from other scopes.\n\nSCA2D has been used for a few years now by the OpenFlexure Microscope project, but may have issue with projects that use different conventions.\n\nIt can:\n\n* Parse any `.scad` file. We don't yet do extensive testing. Please raise an issue if you find a parsing error in SCA2D.\n* Parse included and used `.scad` files and checking variable, function, and module usage in different scopes.\n* Report for a number of code errors, code style issues, and some whitespace issues.\n\nSCA2D is also experimenting with creating documentation while linting.\n\n## How to install\n\nIf you have Python 3.6 or later installed on your machine (and on the PATH) you can install SCA2D from PyPi by running the following command from a terminal\n\n pip install sca2d\n\nto upgrade your current versions of SCA2D run:\n\n pip install sca2d --upgrade\n\nYou can check that SCA2D is installed by running the following:\n\n sca2d -h\n\nyou should see a help screen.\n\n### Install issues\n\nIf you have problems with installation possible problems include:\n\n* You may need to run `pip3` instead of `pip`\n* Python may not be on the PATH, this often happens in Windows depending on how python was installed\n\n## How to run\n\nTo analyse a `.scad` file run:\n\n sca2d filename.scad\n\nThis will print any code messages to the screen.\n\nTo analyse all `.scad` files in a directory run:\n\n sca2d dir_path\n\nThis will also print any code messages to the screen.\n\n**To also generate documentation run.**\n\n sca2d --docs dir_path.\n\nAdditionally the `--project` option can be used to set a project name for the documentation.\n\nIf you wish to inspect the parse tree that SCA2D generates and then uses you can instead run:\n\n sca2d --output-tree filename.scad\n\nthe tree will be printed into a file called `filename.sca2d`.\n\n\n### SCA2D Docstring Conventions for OpenSCAD\n\nTo enable automatic documentation parsing and example image generation, SCA2D defines a simple docstring format for OpenSCAD code. These conventions are enforced and utilised by the SCA2D documentation tooling.\n\n- Use `/* */`-style C comments for docstrings.\n- Do **not** include leading `*`s on each line.\n- Document parameters using Python-style directives:\n - `:param arg1: Description of the argument`\n - `:return:` or `:returns:` to describe return values\n - `:assert condition:` to describe assertions or expected conditions (in place of `:raises:`)\n- Multiline descriptions (for `:param`, `:return:`, or `:assert`) should indent subsequent lines by **4 spaces**.\n- All other content is treated as **Markdown**.\n- Use fenced code blocks (` ``` `) for examples or inline code.\n\n#### Docstring Example\n\n```scad\n/* Create a box with optional bevelled edges.\n\n :param size: A 2D vector specifying the width and height\n :param bevel: Optional bevel radius (default 0)\n\n :return: A 2D shape representing the box\n*/\nmodule box(size, bevel = 0) {\n // ...\n}\n```\n\n#### Rendering images for examples\n\nTo include a rendered image of an example use a fenced code block that begins with ` ```example `. This blocks trigger automatic image generation as part of the documentation build.\n\nCustomisation is currently fairly limited.\n\n* To set the camera angle use the special scad variables (`$vpt`, `$vpr`, and `$vpd`) in your example.\n* By default preview mode is used to use render mode add the word `render` after `example`: ` ```example render`\n* By images have the axes showing, add `no-axes` after `example` to suppress rendering axes: ` ```example no-axes`\n\n#### Other Options for Documenting OpenSCAD\n\nProjects like [`openscad_docsgen`](https://https://github.com/BelfrySCAD/openscad_docsgen) also generate OpenSCAD docs. \n\nWe did consider following the same conventions, however, because `openscad_docsgen` does not parse the SCAD code, their conventions include a lot of repetition of information found in the code (such as function/module signatures). The format also contains a fairly rigid structure to the documentation, prevent simply adding docs as you go to specific functions.\n\nThe SCA2D approach is to parse the SCAD source first, to automatically create module and function signatures, so documentation can focus purely on usage, behaviour, and intent. This avoids redundancy, reduces maintenance overhead, and allows for lightweight Markdown-based docstrings that feel familiar to developers coming from Python or similar languages.\n\nAt the time of writing `openscad_docsgen` is more mature than SCA2D's documentation tooling, and has more options for generating example images.\n\n\n## How to get involved with SCA2D\n\nThe best way to get involved is to find bugs and then [open an issue](https://gitlab.com/bath_open_instrumentation_group/sca2d/-/issues). You could also make changes and open a merge request.\n",
"bugtrack_url": null,
"license": null,
"summary": "A static code analyser for OpenSCAD.",
"version": "0.3.1",
"project_urls": {
"Bug Tracker": "https://gitlab.com/bath_open_instrumentation_group/sca2d/issues",
"Homepage": "https://gitlab.com/bath_open_instrumentation_group/sca2d",
"Source Code": "https://gitlab.com/bath_open_instrumentation_group/sca2d"
},
"split_keywords": [
"linting",
" openscad"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f2e6a9881647e64b625d0f2b82665f9abef1a107f24007ee7db55eba18c03cfc",
"md5": "a7ad0ec115cdb379d0a2373ee802d013",
"sha256": "b2e4a85db77360d7f438f9f95a28fd22b92646789e95a74c2f10b34c42ef6050"
},
"downloads": -1,
"filename": "sca2d-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a7ad0ec115cdb379d0a2373ee802d013",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 57144,
"upload_time": "2025-08-10T22:25:41",
"upload_time_iso_8601": "2025-08-10T22:25:41.212968Z",
"url": "https://files.pythonhosted.org/packages/f2/e6/a9881647e64b625d0f2b82665f9abef1a107f24007ee7db55eba18c03cfc/sca2d-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0b7bdefe4edbabaf47c4af5663bdda49ff9016678b26f9c77d302424be08cde0",
"md5": "5c3b8177881911cd8668feaa97da0ce2",
"sha256": "548652491d50d8becfe599d8aac9dc719c2b3b5a3d89744e5dae6ea516d337f0"
},
"downloads": -1,
"filename": "sca2d-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "5c3b8177881911cd8668feaa97da0ce2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 49992,
"upload_time": "2025-08-10T22:25:42",
"upload_time_iso_8601": "2025-08-10T22:25:42.938861Z",
"url": "https://files.pythonhosted.org/packages/0b/7b/defe4edbabaf47c4af5663bdda49ff9016678b26f9c77d302424be08cde0/sca2d-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-10 22:25:42",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "bath_open_instrumentation_group",
"gitlab_project": "sca2d",
"lcname": "sca2d"
}
