From 70357c7ada8fd5809a3f655f9cdfc0a5b04f6e1f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Wi=C5=9Bniewski?= Date: Tue, 19 Nov 2024 00:22:48 +0100 Subject: [PATCH 1/2] Extend documentation --- docs/{README.md => 00_readme.md} | 2 + docs/{LICENSE.md => 10_license.md} | 0 docs/{Changelog.md => 30_changelog.md} | 0 docs/40_gerber/00_introduction.md | 124 +++++++++++++++ .../10_migrate_from_2_4_x_to_3_x_x.md} | 0 .../20_quick_start/00_introduction.md | 0 .../20_quick_start/01_single_file.md | 10 +- .../20_quick_start/02_multi_file.md | 0 .../20_quick_start/03_project_gerber_job.md | 0 .../20_quick_start/10_custom_color_maps.md | 0 .../20_quick_start/gbrjob_bottom_render.png | Bin .../20_quick_start/render_project.png | Bin .../single_file_from_project.png | Bin .../20_quick_start/single_file_pillow.png | Bin .../20_quick_start/single_file_shapely.svg | 0 .../30_analysis}/00_introduction.md | 0 .../10_stateless_introspection.md | 0 .../30_analysis}/20_stateful_introspection.md | 0 .../40_modify_optimize}/00_introduction.md | 0 .../30_code_optimization.md | 0 .../60_formatter/00_introduction.md | 0 .../60_formatter/10_configuration.md | 0 .../60_formatter/20_extending_formatter.md | 0 .../70_diagnostics/00_introduction.md | 0 .../80_language_server/00_introduction.md | 0 .../80_language_server/10_vsc_integration.md | 0 .../80_language_server/50_features.md | 0 docs/40_gerber/90_extend/00_introduction.md | 0 .../90_extend}/40_extending_ast_nodes.md | 0 .../90_extend}/50_extending_parser.md | 0 .../90_extend}/60_extending_compiler.md | 0 .../70_extending_virtual_machines.md | 0 docs/60_rendering_backends/00_introduction.md | 1 + docs/90_development/00_introduction.md | 1 + docs/90_development/00_setup.md | 50 ------ docs/90_development/10_build.md | 18 --- docs/90_development/10_env_setup.md | 139 +++++++++++++++++ docs/90_development/20_documentation.md | 10 -- docs/90_development/20_packaging.md | 26 ++++ docs/90_development/30_documentation.md | 33 ++++ .../40_contribution_guidelines.md | 143 ++++++++++++++++++ mkdocs.yaml | 7 +- pyproject.toml | 21 +-- 43 files changed, 485 insertions(+), 100 deletions(-) rename docs/{README.md => 00_readme.md} (61%) rename docs/{LICENSE.md => 10_license.md} (100%) rename docs/{Changelog.md => 30_changelog.md} (100%) create mode 100644 docs/40_gerber/00_introduction.md rename docs/{70_gerber/90_migrate_from_2_4_x_to_3_x_x.md => 40_gerber/10_migrate_from_2_4_x_to_3_x_x.md} (100%) rename docs/{70_gerber => 40_gerber}/20_quick_start/00_introduction.md (100%) rename docs/{70_gerber => 40_gerber}/20_quick_start/01_single_file.md (96%) rename docs/{70_gerber => 40_gerber}/20_quick_start/02_multi_file.md (100%) rename docs/{70_gerber => 40_gerber}/20_quick_start/03_project_gerber_job.md (100%) rename docs/{70_gerber => 40_gerber}/20_quick_start/10_custom_color_maps.md (100%) rename docs/{70_gerber => 40_gerber}/20_quick_start/gbrjob_bottom_render.png (100%) rename docs/{70_gerber => 40_gerber}/20_quick_start/render_project.png (100%) rename docs/{70_gerber => 40_gerber}/20_quick_start/single_file_from_project.png (100%) rename docs/{70_gerber => 40_gerber}/20_quick_start/single_file_pillow.png (100%) rename docs/{70_gerber => 40_gerber}/20_quick_start/single_file_shapely.svg (100%) rename docs/{70_gerber => 40_gerber/30_analysis}/00_introduction.md (100%) rename docs/{70_gerber/30_advanced_guide => 40_gerber/30_analysis}/10_stateless_introspection.md (100%) rename docs/{70_gerber/30_advanced_guide => 40_gerber/30_analysis}/20_stateful_introspection.md (100%) rename docs/{70_gerber/30_advanced_guide => 40_gerber/40_modify_optimize}/00_introduction.md (100%) rename docs/{70_gerber/30_advanced_guide => 40_gerber/40_modify_optimize}/30_code_optimization.md (100%) rename docs/{70_gerber => 40_gerber}/60_formatter/00_introduction.md (100%) rename docs/{70_gerber => 40_gerber}/60_formatter/10_configuration.md (100%) rename docs/{70_gerber => 40_gerber}/60_formatter/20_extending_formatter.md (100%) create mode 100644 docs/40_gerber/70_diagnostics/00_introduction.md rename docs/{70_gerber => 40_gerber}/80_language_server/00_introduction.md (100%) rename docs/{70_gerber => 40_gerber}/80_language_server/10_vsc_integration.md (100%) rename docs/{70_gerber => 40_gerber}/80_language_server/50_features.md (100%) create mode 100644 docs/40_gerber/90_extend/00_introduction.md rename docs/{70_gerber/30_advanced_guide => 40_gerber/90_extend}/40_extending_ast_nodes.md (100%) rename docs/{70_gerber/30_advanced_guide => 40_gerber/90_extend}/50_extending_parser.md (100%) rename docs/{70_gerber/30_advanced_guide => 40_gerber/90_extend}/60_extending_compiler.md (100%) rename docs/{70_gerber/30_advanced_guide => 40_gerber/90_extend}/70_extending_virtual_machines.md (100%) create mode 100644 docs/60_rendering_backends/00_introduction.md create mode 100644 docs/90_development/00_introduction.md delete mode 100644 docs/90_development/00_setup.md delete mode 100644 docs/90_development/10_build.md create mode 100644 docs/90_development/10_env_setup.md delete mode 100644 docs/90_development/20_documentation.md create mode 100644 docs/90_development/20_packaging.md create mode 100644 docs/90_development/30_documentation.md create mode 100644 docs/90_development/40_contribution_guidelines.md diff --git a/docs/README.md b/docs/00_readme.md similarity index 61% rename from docs/README.md rename to docs/00_readme.md index b9689343..8d97a821 100644 --- a/docs/README.md +++ b/docs/00_readme.md @@ -1 +1,3 @@ +# Introduction + {% include 'README.md' %} diff --git a/docs/LICENSE.md b/docs/10_license.md similarity index 100% rename from docs/LICENSE.md rename to docs/10_license.md diff --git a/docs/Changelog.md b/docs/30_changelog.md similarity index 100% rename from docs/Changelog.md rename to docs/30_changelog.md diff --git a/docs/40_gerber/00_introduction.md b/docs/40_gerber/00_introduction.md new file mode 100644 index 00000000..f68329fe --- /dev/null +++ b/docs/40_gerber/00_introduction.md @@ -0,0 +1,124 @@ +# Introduction + +## What you will find here + +Welcome to the documentation of Gerber tooling within PyGerber library. This part of +documentation will cover most of the features of PyGerber which have to do with +consuming and changing Gerber files. + +In particular, you can learn here how to: + +- [quickly render PNGs, JPEGs or SVGs from Gerber files](./20_quick_start/01_single_file.md), +- [stack many of them on top each other so they align well](./20_quick_start/02_multi_file.md), +- [consume Gerber Job files](./20_quick_start/03_project_gerber_job.md), +- [perform analysis of Gerber files](./30_analysis/00_introduction.md), +- [modify them](./40_modify_optimize/00_introduction.md), +- [and format them](./60_formatter/00_introduction.md), +- [collect diagnostics](./70_diagnostics/00_introduction.md), +- [use language server](./80_language_server/00_introduction.md), +- [or even extend PyGerber](./90_extend/00_introduction.md). + +Generation of Gerber files is covered separately by +[Gerber code generation](../80_code_generation/00_introduction.md) guide. + +Adding rendering backends is covered by documentation of +[Virtual Machines](../60_rendering_backends/00_introduction.md). + +## Design overview + +In this section we will cover the general design of Gerber tooling within PyGerber. +Let's start with basic stages of Gerber processing which have to be performed to create +PNG image out of Gerber file. + +### Parser + +First of all, Gerber files have to be loaded into memory and parsed into +[Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) (AST). This +is done by a parser, currently PyGerber has only one Gerber parser, based on +[pyparsing](https://pypi.org/project/pyparsing/) library, available as +[`pygerber.gerber.parser.pyparsing.Parser`](../reference/pygerber/gerber/parser/pyparsing/parser.md#pygerber.gerber.parser.pyparsing.parser.Parser) +class. Currently work is being done to provide plugin interface which would allow to use +parsers implemented as separate packages. Alongside that initiative, a +[C++ based Gerber parser](https://github.com/PyGerber/pygerber_gerber_parser_cpp) is +being implemented. + +### Compiler + +After obtaining AST it is converted to a special assembly like format called Rendering +Virtual Machine Commands (RVMC). This conversion is handled by a +[Compiler](../reference/pygerber/gerber/compiler/compiler.md#pygerber.gerber.compiler.compiler.Compiler) +class. RVMC representation is much simpler, it does not differentiate between +rectangles, obrounds, circles and other Gerber constructs, but rather represents +everything as shapes built out of lines and arcs. This simplification allows it to be +very generic and quite easy to implement. + +### Virtual Machine + +Once RVMC is obtained, it is passed to one of the classes inheriting from +[VirtualMachine](../reference/pygerber/vm/vm.md#pygerber.vm.vm.VirtualMachine) class, +which are responsible for "executing" the RVMC (nomenclature based on analogy to +executing assembly code). Depending on the VM chosen, there are different configuration +options available and different type of image will be obtained. Since at the begging we +assumed we want to walk through the process of rendering PNG image, we would have to +choose +[PillowVirtualMachine](../reference/pygerber/vm/pillow/vm.md#pygerber.vm.pillow.vm.PillowVirtualMachine), +which is capable of rendering raster images with +[Pillow](https://pypi.org/project/pillow/) library and exporting them in different +raster formats. + +```mermaid +flowchart TD + src@{ shape: st-rect, label: "Gerber source" } + parser@{ shape: proc, label: "Parser" } + ast@{ shape: st-rect, label: "Abstract Syntax Tree" } + compiler@{ shape: proc, label: "Compiler" } + rvmc@{ shape: st-rect, label: "RVMC" } + vm@{ shape: proc, label: "Virtual Machine" } + image@{ shape: st-rect, label: "Image" } + +src --> parser + +subgraph Parsing + parser --> ast +end + +subgraph Translation + ast --> compiler + compiler --> rvmc +end + +subgraph Rendering + rvmc --> vm + vm --> image +end + +``` + +## Additional processing + +Although rendering is probably the most useful feature of PyGerber, it is not the only +one. PyGerber is capable of performing analysis, formatting and modification of existing +Gerber files. This is done by different classes, which are not part of the rendering +pipeline. All those tools require AST as input, so you have to first parse Gerber file +before you can use them. For example here is processing flow for formatting: + +```mermaid +flowchart TD + src@{ shape: st-rect, label: "Gerber source" } + parser@{ shape: proc, label: "Parser" } + ast@{ shape: st-rect, label: "Abstract Syntax Tree" } + formatter@{ shape: proc, label: "Formatter" } + formatted@{ shape: st-rect, label: "Formatted Gerber source" } + +src --> parser + +subgraph Parsing + parser --> ast +end + +subgraph Formatting + ast --> formatter +end + +formatter --> formatted +``` diff --git a/docs/70_gerber/90_migrate_from_2_4_x_to_3_x_x.md b/docs/40_gerber/10_migrate_from_2_4_x_to_3_x_x.md similarity index 100% rename from docs/70_gerber/90_migrate_from_2_4_x_to_3_x_x.md rename to docs/40_gerber/10_migrate_from_2_4_x_to_3_x_x.md diff --git a/docs/70_gerber/20_quick_start/00_introduction.md b/docs/40_gerber/20_quick_start/00_introduction.md similarity index 100% rename from docs/70_gerber/20_quick_start/00_introduction.md rename to docs/40_gerber/20_quick_start/00_introduction.md diff --git a/docs/70_gerber/20_quick_start/01_single_file.md b/docs/40_gerber/20_quick_start/01_single_file.md similarity index 96% rename from docs/70_gerber/20_quick_start/01_single_file.md rename to docs/40_gerber/20_quick_start/01_single_file.md index 5b3dae95..ef8012f9 100644 --- a/docs/70_gerber/20_quick_start/01_single_file.md +++ b/docs/40_gerber/20_quick_start/01_single_file.md @@ -55,7 +55,7 @@ Check out [Custom color maps](./10_custom_color_maps.md) for more details. [`set_parser_options()`](../../reference/pygerber/gerber/api/__init__.md#pygerber.gerber.api.GerberFile.set_parser_options) allows you to modify advanced parser settings. It is available to allow tweaking predefined parser behavior options. If you need more control than provided here, please -check out [Advanced Guide](../30_advanced_guide/00_introduction.md). `**options` are +check out [Extending Guide](../90_extend/00_introduction.md). `**options` are intentionally not precisely defined here, as they are different for different parser implementations, only way to use this method is to already understand what you are doing. @@ -63,10 +63,10 @@ doing. [`set_compiler_options()`](../../reference/pygerber/gerber/api/__init__.md#pygerber.gerber.api.GerberFile.set_compiler_options) allows you to modify advanced compiler settings. It is available to allow tweaking predefined compiler behavior options. If you need more control than provided here, -please check out [Advanced Guide](../30_advanced_guide/00_introduction.md). `**options` -are intentionally not precisely defined here, as they are different for different -compiler implementations, only way to use this method is to already understand what you -are doing. +please check out [Extending Guide](../90_extend/00_introduction.md). `**options` are +intentionally not precisely defined here, as they are different for different compiler +implementations, only way to use this method is to already understand what you are +doing. ## Rendering Gerber file diff --git a/docs/70_gerber/20_quick_start/02_multi_file.md b/docs/40_gerber/20_quick_start/02_multi_file.md similarity index 100% rename from docs/70_gerber/20_quick_start/02_multi_file.md rename to docs/40_gerber/20_quick_start/02_multi_file.md diff --git a/docs/70_gerber/20_quick_start/03_project_gerber_job.md b/docs/40_gerber/20_quick_start/03_project_gerber_job.md similarity index 100% rename from docs/70_gerber/20_quick_start/03_project_gerber_job.md rename to docs/40_gerber/20_quick_start/03_project_gerber_job.md diff --git a/docs/70_gerber/20_quick_start/10_custom_color_maps.md b/docs/40_gerber/20_quick_start/10_custom_color_maps.md similarity index 100% rename from docs/70_gerber/20_quick_start/10_custom_color_maps.md rename to docs/40_gerber/20_quick_start/10_custom_color_maps.md diff --git a/docs/70_gerber/20_quick_start/gbrjob_bottom_render.png b/docs/40_gerber/20_quick_start/gbrjob_bottom_render.png similarity index 100% rename from docs/70_gerber/20_quick_start/gbrjob_bottom_render.png rename to docs/40_gerber/20_quick_start/gbrjob_bottom_render.png diff --git a/docs/70_gerber/20_quick_start/render_project.png b/docs/40_gerber/20_quick_start/render_project.png similarity index 100% rename from docs/70_gerber/20_quick_start/render_project.png rename to docs/40_gerber/20_quick_start/render_project.png diff --git a/docs/70_gerber/20_quick_start/single_file_from_project.png b/docs/40_gerber/20_quick_start/single_file_from_project.png similarity index 100% rename from docs/70_gerber/20_quick_start/single_file_from_project.png rename to docs/40_gerber/20_quick_start/single_file_from_project.png diff --git a/docs/70_gerber/20_quick_start/single_file_pillow.png b/docs/40_gerber/20_quick_start/single_file_pillow.png similarity index 100% rename from docs/70_gerber/20_quick_start/single_file_pillow.png rename to docs/40_gerber/20_quick_start/single_file_pillow.png diff --git a/docs/70_gerber/20_quick_start/single_file_shapely.svg b/docs/40_gerber/20_quick_start/single_file_shapely.svg similarity index 100% rename from docs/70_gerber/20_quick_start/single_file_shapely.svg rename to docs/40_gerber/20_quick_start/single_file_shapely.svg diff --git a/docs/70_gerber/00_introduction.md b/docs/40_gerber/30_analysis/00_introduction.md similarity index 100% rename from docs/70_gerber/00_introduction.md rename to docs/40_gerber/30_analysis/00_introduction.md diff --git a/docs/70_gerber/30_advanced_guide/10_stateless_introspection.md b/docs/40_gerber/30_analysis/10_stateless_introspection.md similarity index 100% rename from docs/70_gerber/30_advanced_guide/10_stateless_introspection.md rename to docs/40_gerber/30_analysis/10_stateless_introspection.md diff --git a/docs/70_gerber/30_advanced_guide/20_stateful_introspection.md b/docs/40_gerber/30_analysis/20_stateful_introspection.md similarity index 100% rename from docs/70_gerber/30_advanced_guide/20_stateful_introspection.md rename to docs/40_gerber/30_analysis/20_stateful_introspection.md diff --git a/docs/70_gerber/30_advanced_guide/00_introduction.md b/docs/40_gerber/40_modify_optimize/00_introduction.md similarity index 100% rename from docs/70_gerber/30_advanced_guide/00_introduction.md rename to docs/40_gerber/40_modify_optimize/00_introduction.md diff --git a/docs/70_gerber/30_advanced_guide/30_code_optimization.md b/docs/40_gerber/40_modify_optimize/30_code_optimization.md similarity index 100% rename from docs/70_gerber/30_advanced_guide/30_code_optimization.md rename to docs/40_gerber/40_modify_optimize/30_code_optimization.md diff --git a/docs/70_gerber/60_formatter/00_introduction.md b/docs/40_gerber/60_formatter/00_introduction.md similarity index 100% rename from docs/70_gerber/60_formatter/00_introduction.md rename to docs/40_gerber/60_formatter/00_introduction.md diff --git a/docs/70_gerber/60_formatter/10_configuration.md b/docs/40_gerber/60_formatter/10_configuration.md similarity index 100% rename from docs/70_gerber/60_formatter/10_configuration.md rename to docs/40_gerber/60_formatter/10_configuration.md diff --git a/docs/70_gerber/60_formatter/20_extending_formatter.md b/docs/40_gerber/60_formatter/20_extending_formatter.md similarity index 100% rename from docs/70_gerber/60_formatter/20_extending_formatter.md rename to docs/40_gerber/60_formatter/20_extending_formatter.md diff --git a/docs/40_gerber/70_diagnostics/00_introduction.md b/docs/40_gerber/70_diagnostics/00_introduction.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/70_gerber/80_language_server/00_introduction.md b/docs/40_gerber/80_language_server/00_introduction.md similarity index 100% rename from docs/70_gerber/80_language_server/00_introduction.md rename to docs/40_gerber/80_language_server/00_introduction.md diff --git a/docs/70_gerber/80_language_server/10_vsc_integration.md b/docs/40_gerber/80_language_server/10_vsc_integration.md similarity index 100% rename from docs/70_gerber/80_language_server/10_vsc_integration.md rename to docs/40_gerber/80_language_server/10_vsc_integration.md diff --git a/docs/70_gerber/80_language_server/50_features.md b/docs/40_gerber/80_language_server/50_features.md similarity index 100% rename from docs/70_gerber/80_language_server/50_features.md rename to docs/40_gerber/80_language_server/50_features.md diff --git a/docs/40_gerber/90_extend/00_introduction.md b/docs/40_gerber/90_extend/00_introduction.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/70_gerber/30_advanced_guide/40_extending_ast_nodes.md b/docs/40_gerber/90_extend/40_extending_ast_nodes.md similarity index 100% rename from docs/70_gerber/30_advanced_guide/40_extending_ast_nodes.md rename to docs/40_gerber/90_extend/40_extending_ast_nodes.md diff --git a/docs/70_gerber/30_advanced_guide/50_extending_parser.md b/docs/40_gerber/90_extend/50_extending_parser.md similarity index 100% rename from docs/70_gerber/30_advanced_guide/50_extending_parser.md rename to docs/40_gerber/90_extend/50_extending_parser.md diff --git a/docs/70_gerber/30_advanced_guide/60_extending_compiler.md b/docs/40_gerber/90_extend/60_extending_compiler.md similarity index 100% rename from docs/70_gerber/30_advanced_guide/60_extending_compiler.md rename to docs/40_gerber/90_extend/60_extending_compiler.md diff --git a/docs/70_gerber/30_advanced_guide/70_extending_virtual_machines.md b/docs/40_gerber/90_extend/70_extending_virtual_machines.md similarity index 100% rename from docs/70_gerber/30_advanced_guide/70_extending_virtual_machines.md rename to docs/40_gerber/90_extend/70_extending_virtual_machines.md diff --git a/docs/60_rendering_backends/00_introduction.md b/docs/60_rendering_backends/00_introduction.md new file mode 100644 index 00000000..e10b99d0 --- /dev/null +++ b/docs/60_rendering_backends/00_introduction.md @@ -0,0 +1 @@ +# Introduction diff --git a/docs/90_development/00_introduction.md b/docs/90_development/00_introduction.md new file mode 100644 index 00000000..e10b99d0 --- /dev/null +++ b/docs/90_development/00_introduction.md @@ -0,0 +1 @@ +# Introduction diff --git a/docs/90_development/00_setup.md b/docs/90_development/00_setup.md deleted file mode 100644 index 6b002bef..00000000 --- a/docs/90_development/00_setup.md +++ /dev/null @@ -1,50 +0,0 @@ -# Setup - -This project uses `Python` programming language and requires at least python `3.8` for -development and distribution. Development dependencies -[`poetry`](https://pypi.org/project/poetry/) for managing dependencies and distribution -building. It is necessary to perform any operations in development environment. - -To install poetry globally (preferred way) use `pip` in terminal: - -``` -pip install poetry -``` - -Then use - -``` -poetry shell -``` - -to spawn new shell with virtual environment activated. Virtual environment will be -indicated by terminal prompt prefix `(pygerber-py3.8)`, version indicated in prefix -depends on used version of Python interpreter. - -Within shell with active virtual environment use: - -``` -poetry install --sync -``` - -To install all dependencies. Every time you perform a `git pull` or change a branch, you -should call this command to make sure you have the correct versions of dependencies. - -Afterwards you will have to also setup pre-commit hooks to avoid problems with code -quality during review. To do so, use: - -``` -poe install-hooks -``` - -Hooks will run automatically before every commit. If you want to run them manually, use: - -``` -poe run-code-quality-checks -``` - -To run unit test suite, use: - -``` -poe run-unit-tests -``` diff --git a/docs/90_development/10_build.md b/docs/90_development/10_build.md deleted file mode 100644 index da1049c9..00000000 --- a/docs/90_development/10_build.md +++ /dev/null @@ -1,18 +0,0 @@ -# Build from source - -To build PyGerber from source You have to set up [Development](#development) environment -first. Make sure you have `poetry` environment activated with: - -``` -poetry shell -``` - -With environment active it should be possible to build wheel and source distribution -with: - -``` -poetry build -``` - -Check `dist` directory within current working directory, `pygerber-x.y.z.tar.gz` and -`pygerber-x.y.z-py3-none-any.whl` should be there. diff --git a/docs/90_development/10_env_setup.md b/docs/90_development/10_env_setup.md new file mode 100644 index 00000000..63d300de --- /dev/null +++ b/docs/90_development/10_env_setup.md @@ -0,0 +1,139 @@ +# Environment setup + +## Development virtual environment + +This project uses `Python` programming language and requires at least python `3.8` in +development and production environment to function. During development, PyGerber relies +on [poetr](https://pypi.org/project/poetry/) for dependency management, creation of +development virtual environment and packaging. To work on PyGerber, you will need to +install poetry on your system. You can find official poetry installation guidelines +[here](https://python-poetry.org/docs/#installation). We recommend installing poetry +globally, unless on linux distribution, in such case distribution native approach should +be taken, usually with distribution specific package manager. + +To install poetry globally you can use `pip` (or any other PyPI compatible package +manager) in terminal: + +``` +pip install poetry +``` + +!!! warning + + Make sure you are installing latest version of poetry, or at least `>=1.8` as in the + past poetry had minor issues with stability during installation of dependencies. + +After installing poetry, if you haven't already, clone the repository with + +``` +git clone https://github.com/Argmaster/pygerber +``` + +and navigate to project root directory. Once there, use: + +``` +poetry shell +``` + +to create a development virtual environment and enter a shell with virtual environment +activated. Virtual environment will be indicated by terminal prompt prefix +`(pygerber-pyX.Y)`, (where `X.Y` is python version). + +Afterwards you can start process of installation of development dependencies. Use: + +``` +poetry install --sync --extras=all --with=docs,style +``` + +To install all dependencies, including optional ones. Every time you perform a +`git pull` or change a branch, you should run this command again to make sure you have +the correct versions of dependencies. + +## Git hooks + +PyGerber project uses [pre-commit](https://pypi.org/project/pre-commit/) to run git +hooks to ensure high quality of code committed to the repository. You can skip +installation of hooks if you want, but you will still have to meet their requirements +after they are run by CI/CD pipeline. Preferably, you should install them locally and +keep an eye on their status: + +``` +poe install-hooks +``` + +!!! warning + + Don't confuse `poe` with `poetry`, `poe` is a command line tool for running simple + sequences of commands while `poetry` is a package manager and virtual environment + manager. + +You can check if your hooks were setup correctly by running: + +``` +poe test-style +``` + +Here is reference output of `poe test-style`: + +> ``` +> Poe => poetry run pre-commit run --all-files -v +> prettier.................................................................Passed +> - hook id: prettier +> - duration: 0.83s +> check illegal windows names..........................(no files to check)Skipped +> - hook id: check-illegal-windows-names +> check for case conflicts.................................................Passed +> - hook id: check-case-conflict +> - duration: 0.5s +> check for merge conflicts................................................Passed +> - hook id: check-merge-conflict +> - duration: 0.38s +> check for case conflicts.................................................Passed +> - hook id: check-case-conflict +> - duration: 0.48s +> trim trailing whitespace.................................................Passed +> - hook id: trailing-whitespace +> - duration: 0.23s +> debug statements (python)................................................Passed +> - hook id: debug-statements +> - duration: 0.23s +> fix end of files.........................................................Passed +> - hook id: end-of-file-fixer +> - duration: 0.2s +> fix utf-8 byte order marker..............................................Passed +> - hook id: fix-byte-order-marker +> - duration: 0.22s +> check for added large files..............................................Passed +> - hook id: check-added-large-files +> - duration: 0.52s +> check toml...............................................................Passed +> - hook id: check-toml +> - duration: 0.09s +> mixed line ending........................................................Passed +> - hook id: mixed-line-ending +> - duration: 0.22s +> trim trailing whitespace.................................................Passed +> - hook id: trailing-whitespace +> - duration: 0.22s +> debug statements (python)................................................Passed +> - hook id: debug-statements +> - duration: 0.22s +> ruff.....................................................................Passed +> - hook id: ruff +> - duration: 0.11s +> +> All checks passed! +> +> ruff-format..............................................................Passed +> - hook id: ruff-format +> - duration: 0.11s +> +> 284 files left unchanged +> +> mypy.....................................................................Passed +> - hook id: mypy +> - duration: 15.95s +> +> Poe => poetry run mypy --config-file=pyproject.toml src/pygerber/ test/ +> Success: no issues found in 279 source files +> ``` diff --git a/docs/90_development/20_documentation.md b/docs/90_development/20_documentation.md deleted file mode 100644 index 8441df5e..00000000 --- a/docs/90_development/20_documentation.md +++ /dev/null @@ -1,10 +0,0 @@ -# Build documentation - -To build the documentation please first basic environment setup from -`Development > Setup` section. - -To build the documentation You have to run following command: - -``` -mkdocs build -``` diff --git a/docs/90_development/20_packaging.md b/docs/90_development/20_packaging.md new file mode 100644 index 00000000..447c4474 --- /dev/null +++ b/docs/90_development/20_packaging.md @@ -0,0 +1,26 @@ +# Package + +Since PyGerber is a pure Python package, there is nothing to compile and there is no +special build step before packaging. + +To build PyGerber `wheel` or `sdist` package from source you have to first set up +development environment as described in [Environment setup](./10_env_setup.md) section. +After completing initial setup of development environment, you should have +[poetry](https://pypi.org/project/poetry/) installed on your system. To build both wheel +and source distribution packages, use following command: + +``` +poetry build +``` + +Check `dist` directory within current working directory, `pygerber-x.y.z.tar.gz` and +`pygerber-x.y.z-py3-none-any.whl` files should be present there. You can use `pip` to +directly install them: + +!!! warning + + Replace `x.y.z` with actual version number. + +``` +pip install dist/pygerber-x.y.z.tar.gz +``` diff --git a/docs/90_development/30_documentation.md b/docs/90_development/30_documentation.md new file mode 100644 index 00000000..86959f83 --- /dev/null +++ b/docs/90_development/30_documentation.md @@ -0,0 +1,33 @@ +# Documentation + +PyGerber uses [MkDocs](https://pypi.org/project/mkdocs/) library and Markdown syntax to +write documentation. Documentation can be divided into two parts: + +- manually written documentation +- automatically generated documentation + +First one is stored in `docs` directory and is written in Markdown. Second one is +generated from docstrings in source code using +[mkdocstrings](https://pypi.org/project/mkdocstrings/) package and it is automatically +collected during documentation build. + +Before building documentation, make sure that you have completed development environment +setup described in [Environment setup](./10_env_setup.md) section. After completing +initial setup you should be able to continue following this guide. + +To generate HTML/CSS/JS files containing distribution of documentation, use following +command: + +``` +mkdocs build +``` + +This command will create `site` directory and place all necessary HTML/CSS/JS files +there. + +MkDocs also offers a live preview of documentation with automatic reload on file change. +To start live preview, use following command: + +``` +mkdocs serve +``` diff --git a/docs/90_development/40_contribution_guidelines.md b/docs/90_development/40_contribution_guidelines.md new file mode 100644 index 00000000..30288c31 --- /dev/null +++ b/docs/90_development/40_contribution_guidelines.md @@ -0,0 +1,143 @@ +# Contribution guidelines + +Recommended way to contribute to PyGerber is to fork the repository, create a new +branch, make changes and submit a pull request. After submitting a pull request, one of +PyGerber maintainers will review it and possibly allow CI to run tests on your changes. + +```mermaid +graph LR + A[Fork] --> B[Branch] + B --> C[Commit] + C --> D[Pull request] + D --> E[Review] + E --> F[Merge] +``` + +Maintainer may ask for additional changes or provide feedback on your pull request. +Please be patient and polite, maintainers are volunteers and they may not be able to +respond immediately. If you are not sure about something, feel free to ask for help in +the pull request comments. We encourage open and respectful communication. + +When requested to make changes to your pull request, please do so in a new commit. This +will allow maintainers to easily see what has changed since last review. + +!!! warning + + Avoid force pushing and squashing existing commits unless asked to do so. Those + operations obfuscate history and make it harder to incrementally review changes. + +Within continuous integration pipeline PyGerber runs tests on multiple Python versions, +multiple platforms and verifies code quality with tools listed in +`.pre-commit-config.yaml`. If your changes do not pass tests or code quality checks, you +will be asked to fix them before your pull request can be merged. We recommend you to +run tests locally before submitting a pull request to make the process quicker. + +{{ include_code(".pre-commit-config.yaml", "yaml", title=".pre-commit-config.yaml", linenums="1") }} + +!!! warning + + Before trying to run those commands, have look at [Environment setup](./10_env_setup.md). + +To run style checks locally, you can use following commands: + +```bash +poe test-style +``` + +!!! warning + + This will run all code quality related checks, but does not include any of behavior + (unit or end to end) tests. + +To run unit and end to end tests, use following commands: + +```bash +poe test-all +``` + +!!! warning + + `test-all` target does **not** include style checks itself, they have to be run + separately. + +When adding new features, please include necessary documentation updates and test cases. +Tests are necessary for even smallest changes to avoid regressions, ensuring that your +changes will continue to function as expected in the future. Test cases should provide +coverage of your change close to 90%. Coverage is reported at the end of `test-all` run. + +For reference, here is an example of coverage report: + +``` +---------- coverage: platform linux, python 3.8.18-final-0 ----------- +Name Stmts Miss Cover Missing +---------------------------------------------------------------------------------------- +src/pygerber/__main__.py 4 4 0% 3-8 +src/pygerber/builder/gerber.py 425 30 93% 215, 243, 246, 266, 415-418, 429, 637, 891, 913, 932, 938-939, 942-943, 946-947, 952, 997-998, 1448-1459, 1570-1571, 1640, 1680, 1729, 1745 +src/pygerber/builder/rvmc.py 88 16 82% 105-109, 119-124, 175-176, 179-180, 208-209, 236-237, 275-276, 295-296 +src/pygerber/common/error.py 4 1 75% 10 +src/pygerber/common/position.py 43 43 0% 3-83 +src/pygerber/console/commands.py 38 4 89% 21-26 +src/pygerber/gerber/api/_composite_view.py 35 1 97% 95 +src/pygerber/gerber/api/_enums.py 68 7 90% 123, 129, 136-137, 142, 145, 148 +src/pygerber/gerber/api/_gerber_file.py 224 24 89% 109, 114, 122, 130, 248, 278, 283, 309, 329, 398-399, 474, 479-492, 499, 537, 560 +src/pygerber/gerber/api/_gerber_job_file.py 119 4 97% 146, 191, 209, 218 +src/pygerber/gerber/api/_project.py 19 1 95% 42 +src/pygerber/gerber/ast/ast_visitor.py 387 3 99% 781, 794, 798 +src/pygerber/gerber/ast/errors.py 32 5 84% 28, 47-48, 57-58 +src/pygerber/gerber/ast/expression_eval_visitor.py 59 3 95% 100-102 +src/pygerber/gerber/ast/node_finder.py 61 6 90% 51, 54-55, 68-69, 92 +src/pygerber/gerber/ast/nodes/aperture/AB.py 13 1 92% 32 +src/pygerber/gerber/ast/nodes/aperture/AM.py 13 1 92% 32 +src/pygerber/gerber/ast/nodes/aperture/SR.py 13 1 92% 32 +src/pygerber/gerber/ast/nodes/attribute/TA.py 53 3 94% 24, 36, 106 +src/pygerber/gerber/ast/nodes/attribute/TF.py 107 4 96% 27, 39, 216, 225 +src/pygerber/gerber/ast/nodes/attribute/TO.py 159 14 91% 25, 37, 123, 144, 165, 186, 207, 228, 249, 270, 291, 312, 333, 357 +src/pygerber/gerber/ast/nodes/base.py 35 4 89% 45, 52, 57, 78 +src/pygerber/gerber/ast/nodes/enums.py 124 2 98% 78, 124 +src/pygerber/gerber/ast/nodes/invalid.py 9 2 78% 22, 28 +src/pygerber/gerber/ast/nodes/math/constant.py 16 1 94% 32 +src/pygerber/gerber/ast/nodes/math/parenthesis.py 9 1 89% 30 +src/pygerber/gerber/ast/state_tracking_visitor.py 451 55 88% 125-126, 130, 135, 190, 195, 214, 238, 317, 360, 435, 501, 509, 517, 525, 667-668, 765-767, 787, 794-799, 843, 852, 861, 870, 877-879, 896-898, 902-904, 908-910, 914-917, 927-930, 934-937, 950 +src/pygerber/gerber/compiler/compiler.py 453 26 94% 155, 183-196, 355, 480, 500, 515-525, 553, 631, 689, 709, 878-883, 913, 921, 924, 1023-1024 +src/pygerber/gerber/compiler/errors.py 15 6 60% 21-26, 33-34, 41 +src/pygerber/gerber/formatter/formatter.py 942 50 95% 219, 252, 259, 271, 278, 287, 292, 297, 321-330, 346-348, 352-357, 361-363, 369-370, 380, 587-588, 813-817, 840-844, 977, 985, 1124, 1133, 1267-1268, 1281-1282 +src/pygerber/gerber/parser/__init__.py 11 2 82% 74-75 +src/pygerber/gerber/parser/pyparsing/grammar.py 387 7 98% 217, 220, 228, 253, 256, 1220, 1267 +src/pygerber/gerber/pygments.py 34 34 0% 3-191 +src/pygerber/gerber/spec/rev_2024_05.py 257 20 92% 15, 20, 34, 39-40, 45, 261, 269, 277, 285, 292, 299, 306, 313, 320, 328, 336, 344, 352, 360 +src/pygerber/vm/__init__.py 15 2 87% 38-39 +src/pygerber/vm/commands/shape_segments/shape_segment.py 11 2 82% 24, 28 +src/pygerber/vm/pillow/errors.py 7 2 71% 16-19 +src/pygerber/vm/pillow/vm.py 154 10 94% 52, 58-59, 71-72, 88, 198, 230, 311, 361 +src/pygerber/vm/rvmc.py 8 1 88% 19 +src/pygerber/vm/shapely/vm.py 171 11 94% 41-42, 63, 89-93, 140, 167, 209, 325, 364 +src/pygerber/vm/types/color.py 63 22 65% 131-154, 167, 171 +src/pygerber/vm/types/layer_id.py 10 1 90% 20 +src/pygerber/vm/types/matrix.py 53 2 96% 114, 122 +src/pygerber/vm/types/model.py 8 1 88% 23 +src/pygerber/vm/types/vector.py 94 11 88% 45, 58, 68, 78, 84, 90, 96, 102, 108, 167-169 +src/pygerber/vm/vm.py 147 1 99% 299 +---------------------------------------------------------------------------------------- +TOTAL 6835 452 93% + +126 files skipped due to complete coverage. + +===== 1583 passed, 28 skipped, 14 xfailed, 2 warnings in 586.85s (0:09:46) ===== +generating index: 726/727 +``` + +Parts of code that are not covered will have to be marked with `# pragma: no cover`. Be +prepared to justify to maintainers why you didn't cover those parts of code if they ask +about it. + +In most cases after complying with requirements mentioned above, your pull request will +be merged by one of the PyGerber maintainers. We will make sure to include you in the +`CHANGELOG.md` and release notes. + +PyGerber maintainers reserve the right to reject any pull request without providing +reasons. However, they will try to provide feedback and guidance on how to improve your +contribution. + +Please comply with +[GitHub Community Guidelines](https://docs.github.com/en/site-policy/github-terms/github-community-guidelines) +while contributing to PyGerber. diff --git a/mkdocs.yaml b/mkdocs.yaml index a0b33496..8b26f0ba 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -24,7 +24,6 @@ theme: features: - content.action.edit - - navigation.instant - navigation.tracking - navigation.sections - navigation.top @@ -33,6 +32,7 @@ theme: - search.highlight - search.share - content.code.copy + - header.autohide icon: repo: fontawesome/brands/github @@ -129,6 +129,11 @@ extra: version: # https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/ provider: mike + social: + - icon: fontawesome/brands/gitlab + link: https://gitlab.com/Argmaster/pygerber + - icon: fontawesome/brands/github + link: https://github.com/Argmaster/pygerber hooks: - docs/hooks.py diff --git a/pyproject.toml b/pyproject.toml index 01833dd1..e4717c71 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -139,7 +139,6 @@ gerber_lexer = "pygerber.gerber.pygments:GerberLexer" [tool.poe.tasks] # ------------------------------------------------------------------------------------- install-hooks = [ - { cmd = "poetry install --sync --with=docs,style --extras=all --no-ansi" }, { cmd = "poetry run python -m scripts.install_hooks" }, { cmd = "poetry run pre-commit install --install-hooks --overwrite" }, ] @@ -147,27 +146,19 @@ install-hooks = [ prepare-test-style = [ { cmd = "poetry install --sync --with=docs,style --extras=all --no-ansi" }, ] -test-style = [ - { cmd = "poetry run pre-commit run --all-files -v" }, -] +test-style = [{ cmd = "poetry run pre-commit run --all-files -v" }] # --------- All --------- -prepare-test-all = [ - { cmd = "poetry install --sync --extras=all --no-ansi" }, -] +prepare-test-all = [{ cmd = "poetry install --sync --extras=all --no-ansi" }] test-all = [ { cmd = "poetry run pytest -s -n logical --cov=pygerber --cov-report=term-missing:skip-covered test/" }, ] # --------- Unit --------- -prepare-test-unit = [ - { cmd = "poetry install --sync --extras=all --no-ansi" }, -] +prepare-test-unit = [{ cmd = "poetry install --sync --extras=all --no-ansi" }] test-unit = [ { cmd = "poetry run pytest -s -n logical --cov=pygerber --cov-report=term-missing:skip-covered test/unit/" }, ] # --------- E2E --------- -prepare-test-e2e = [ - { cmd = "poetry install --sync --extras=all --no-ansi" }, -] +prepare-test-e2e = [{ cmd = "poetry install --sync --extras=all --no-ansi" }] test-e2e = [ { cmd = "poetry run pytest -s -n logical --cov=pygerber --cov-report=term-missing:skip-covered test/e2e/" }, ] @@ -179,9 +170,7 @@ test-type = [ { cmd = "poetry run mypy --config-file=pyproject.toml src/pygerber/ test/" }, ] # --------- No Extras --------- -prepare-test-no-extras = [ - { cmd = "poetry install --sync --no-ansi" }, -] +prepare-test-no-extras = [{ cmd = "poetry install --sync --no-ansi" }] test-no-extras = [ { cmd = "poetry run pytest -s -n logical --cov=pygerber --cov-report=term-missing:skip-covered --exclude-tags=extras test/" }, ] From 5de1bd8c0076c9d2fa6d3fd10598390eca819c9d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Wi=C5=9Bniewski?= Date: Tue, 19 Nov 2024 00:40:16 +0100 Subject: [PATCH 2/2] Fix documentation entry point --- docs/{00_readme.md => README.md} | 2 -- 1 file changed, 2 deletions(-) rename docs/{00_readme.md => README.md} (61%) diff --git a/docs/00_readme.md b/docs/README.md similarity index 61% rename from docs/00_readme.md rename to docs/README.md index 8d97a821..b9689343 100644 --- a/docs/00_readme.md +++ b/docs/README.md @@ -1,3 +1 @@ -# Introduction - {% include 'README.md' %}