diff --git a/docs/40_gerber/10_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 index 3a8cc1f4..67a07417 100644 --- a/docs/40_gerber/10_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 @@ -1 +1,10 @@ # Migrating from 2.4.x to 3.x.x + +PyGerber 3.0.0 is a major rewrite of the library. Most of the library was rewritten from +scratch, a lot of nomenclature has changes and layout of the library has been +reorganized. This document is intended to provide a help in navigating through the +changes and migrating your code from 2.4.x to 3.x.x. We are especially concerned with +the introspection/analysis APIs which were significantly simplified. + +Unfortunately, this documentation is yet to be written. I am doing my best to provide it +before release 3.0.0 so stay tuned! diff --git a/docs/40_gerber/20_quick_start/10_custom_color_maps.md b/docs/40_gerber/20_quick_start/10_custom_color_maps.md index ec6a7e4c..7aa26fdc 100644 --- a/docs/40_gerber/20_quick_start/10_custom_color_maps.md +++ b/docs/40_gerber/20_quick_start/10_custom_color_maps.md @@ -1,3 +1,4 @@ # Custom color maps -TODO before 3.0.0 +Unfortunately, this documentation is yet to be written. I am doing my best to provide it +before release 3.0.0 so stay tuned! diff --git a/docs/40_gerber/25_command_line/00_introduction.md b/docs/40_gerber/25_command_line/00_introduction.md deleted file mode 100644 index 7f6576c9..00000000 --- a/docs/40_gerber/25_command_line/00_introduction.md +++ /dev/null @@ -1,8 +0,0 @@ -# Introduction - -Welcome to the PyGerber command line interface documentation. This documentation is -intended to guide you through the usage of the command line interface of PyGerber. - -Unfortunately, currently this documentation is under construction. You can still -discover most of the features using `--help` option in command line with each -subcommand. diff --git a/docs/40_gerber/25_command_line/20_gerber.md b/docs/40_gerber/25_command_line/20_gerber.md deleted file mode 100644 index 9f1b6d0e..00000000 --- a/docs/40_gerber/25_command_line/20_gerber.md +++ /dev/null @@ -1 +0,0 @@ -# Gerber diff --git a/docs/40_gerber/30_analysis/00_introduction.md b/docs/40_gerber/30_analysis/00_introduction.md index e10b99d0..cd3f911f 100644 --- a/docs/40_gerber/30_analysis/00_introduction.md +++ b/docs/40_gerber/30_analysis/00_introduction.md @@ -1 +1,8 @@ # Introduction + +Welcome to the Gerber code analysis documentation. This documentation is intended to +provide a friendly guide to the APIs within PyGerber which can be used to analyze Gerber +files. + +Unfortunately, this documentation is yet to be written. I am doing my best to provide it +before release 3.0.0 so stay tuned! diff --git a/docs/40_gerber/30_analysis/10_stateless_introspection.md b/docs/40_gerber/30_analysis/10_stateless_introspection.md index 6a0d859c..053adaa4 100644 --- a/docs/40_gerber/30_analysis/10_stateless_introspection.md +++ b/docs/40_gerber/30_analysis/10_stateless_introspection.md @@ -1 +1,4 @@ # Stateless Introspection + +Unfortunately, this documentation is yet to be written. I am doing my best to provide it +before release 3.0.0 so stay tuned! diff --git a/docs/40_gerber/30_analysis/20_stateful_introspection.md b/docs/40_gerber/30_analysis/20_stateful_introspection.md index 2b87a559..68be146b 100644 --- a/docs/40_gerber/30_analysis/20_stateful_introspection.md +++ b/docs/40_gerber/30_analysis/20_stateful_introspection.md @@ -1 +1,4 @@ # Stateful Introspection + +Unfortunately, this documentation is yet to be written. I am doing my best to provide it +before release 3.0.0 so stay tuned! diff --git a/docs/40_gerber/40_modify_optimize/00_introduction.md b/docs/40_gerber/40_modify_optimize/00_introduction.md index b1859c33..986b3f30 100644 --- a/docs/40_gerber/40_modify_optimize/00_introduction.md +++ b/docs/40_gerber/40_modify_optimize/00_introduction.md @@ -1,11 +1,7 @@ # Introduction -## Steps +Welcome to the Gerber Optimizer documentation. This documentation is intended to provide +a comprehensive overview of the Gerber Optimizer including usage, options and examples. -### Overview - -### Parser - -### Compiler - -### Virtual Machines +Unfortunately, the Gerber Optimizer is not yet implemented and documentation is yet to +be written. I am doing my best to provide it before release 3.0.0, stay tuned! diff --git a/docs/40_gerber/40_modify_optimize/30_code_optimization.md b/docs/40_gerber/40_modify_optimize/30_code_optimization.md index 30139962..bb244ff8 100644 --- a/docs/40_gerber/40_modify_optimize/30_code_optimization.md +++ b/docs/40_gerber/40_modify_optimize/30_code_optimization.md @@ -1 +1,4 @@ # Code optimization + +Unfortunately, this documentation is yet to be written. I am doing my best to provide it +before release 3.0.0 so stay tuned! diff --git a/docs/40_gerber/60_formatter/00_introduction.md b/docs/40_gerber/60_formatter/00_introduction.md index fbb6abd0..df8f2f57 100644 --- a/docs/40_gerber/60_formatter/00_introduction.md +++ b/docs/40_gerber/60_formatter/00_introduction.md @@ -29,5 +29,5 @@ out. This is where the Gerber Formatter comes in handy. The Gerber Formatter can be used both as a command line tool and as a library. The command line tool can be accessed via `pygerber gerber format` subcommand while library API is available through `pygerber.gerber.formatter` module. Command line usage is -covered in [Gerber](../25_command_line/20_gerber.md) command line documentation while +covered in [Gerber](../../25_command_line/20_gerber.md) command line documentation while API usage and configuration options are covered in [API usage](./05_api_usage.md). diff --git a/docs/40_gerber/60_formatter/05_api_usage.md b/docs/40_gerber/60_formatter/05_api_usage.md index 09bf8b32..91662692 100644 --- a/docs/40_gerber/60_formatter/05_api_usage.md +++ b/docs/40_gerber/60_formatter/05_api_usage.md @@ -20,6 +20,6 @@ string. The formatter can be configured using `Options` object. The object can be passed to `format` and `formats` functions as a optional `options` argument. You can find full -option reference [here](../reference/pygerber/gerber/formatter/options.html). +option reference [here](../../reference/pygerber/gerber/formatter/options.md). {{ include_code("test/examples/gerberx3/formatter/_20_format_with_options.py", "docspygerberlexer", title="options_example.py", linenums="1") }} diff --git a/docs/40_gerber/70_diagnostics/00_introduction.md b/docs/40_gerber/70_diagnostics/00_introduction.md index e69de29b..0d0ea3f6 100644 --- a/docs/40_gerber/70_diagnostics/00_introduction.md +++ b/docs/40_gerber/70_diagnostics/00_introduction.md @@ -0,0 +1,4 @@ +# Introduction + +Unfortunately, this documentation is yet to be written. I am doing my best to provide it +before release 3.0.0 so stay tuned! diff --git a/docs/40_gerber/80_language_server/00_introduction.md b/docs/40_gerber/80_language_server/00_introduction.md index e10b99d0..0d0ea3f6 100644 --- a/docs/40_gerber/80_language_server/00_introduction.md +++ b/docs/40_gerber/80_language_server/00_introduction.md @@ -1 +1,4 @@ # Introduction + +Unfortunately, this documentation is yet to be written. I am doing my best to provide it +before release 3.0.0 so stay tuned! diff --git a/docs/40_gerber/80_language_server/10_vsc_integration.md b/docs/40_gerber/80_language_server/10_vsc_integration.md index 0bcfe98d..ca5f92a8 100644 --- a/docs/40_gerber/80_language_server/10_vsc_integration.md +++ b/docs/40_gerber/80_language_server/10_vsc_integration.md @@ -1 +1,4 @@ # Visual Studio Code Integration + +Unfortunately, this documentation is yet to be written. I am doing my best to provide it +before release 3.0.0 so stay tuned! diff --git a/docs/40_gerber/80_language_server/50_features.md b/docs/40_gerber/80_language_server/50_features.md index ead02231..0fb4dea7 100644 --- a/docs/40_gerber/80_language_server/50_features.md +++ b/docs/40_gerber/80_language_server/50_features.md @@ -1 +1,4 @@ # Features + +Unfortunately, this documentation is yet to be written. I am doing my best to provide it +before release 3.0.0 so stay tuned! diff --git a/docs/40_gerber/90_extend/00_introduction.md b/docs/40_gerber/90_extend/00_introduction.md index e69de29b..0d0ea3f6 100644 --- a/docs/40_gerber/90_extend/00_introduction.md +++ b/docs/40_gerber/90_extend/00_introduction.md @@ -0,0 +1,4 @@ +# Introduction + +Unfortunately, this documentation is yet to be written. I am doing my best to provide it +before release 3.0.0 so stay tuned! diff --git a/docs/40_gerber/90_extend/40_extending_ast_nodes.md b/docs/40_gerber/90_extend/40_extending_ast_nodes.md index ed5cd71c..ec2eee22 100644 --- a/docs/40_gerber/90_extend/40_extending_ast_nodes.md +++ b/docs/40_gerber/90_extend/40_extending_ast_nodes.md @@ -1 +1,4 @@ # Extending AST Nodes + +Unfortunately, this documentation is yet to be written. I am doing my best to provide it +before release 3.0.0 so stay tuned! diff --git a/docs/50_command_line/00_introduction.md b/docs/50_command_line/00_introduction.md new file mode 100644 index 00000000..a859ab5f --- /dev/null +++ b/docs/50_command_line/00_introduction.md @@ -0,0 +1,25 @@ +# Introduction + +Welcome to the PyGerber command line interface documentation. This documentation is +intended to guide you through the usage of the command line interface of PyGerber. + +PyGerber command line can be accessed via `pygerber` command: + +```bash +pygerber --version +``` + +Alternatively, executing PyGerber package as main module will yield the same result: + +```bash +python -m pygerber --version +``` + +Only root package supports direct execution. Features of subpackages, eg. formatter can +be accessed by subcommands: + +```bash +pygerber gerber format --help +``` + +But they don't support direct execution as main module. diff --git a/docs/50_command_line/20_gerber.md b/docs/50_command_line/20_gerber.md new file mode 100644 index 00000000..72edc48a --- /dev/null +++ b/docs/50_command_line/20_gerber.md @@ -0,0 +1,91 @@ +# Gerber + +Welcome to the Gerber focused part of PyGerber command line interface documentation. +This documentation is intended to show you how to use Gerber related command line tools +available in PyGerber. + +## Image conversions + +PyGerber offers a set of tools to convert Gerber files to raster and vector images. This +section will guide you through the process of converting Gerber files to images. All +supported image conversions can be listed with: + +```bash +pygerber gerber convert --help +``` + +You can expect formats like PNG, JPEG and SVG to be present there. + +!!! note + + SVG image format support requires a vector rendering engine, currently this means + `shapely` extras set is required for SVG conversion to show up in the help. + Preferably, you should use PyGerber extras set in case in future more dependencies + will be required: + + ```bash + pip install pygerber[shapely] + ``` + + You can also just install all optional extras with: + + ```bash + pip install pygerber[all] + ``` + + This way you won't miss on any of the useful features. + +Let's have look at an example of how one could convert a Gerber file to a PNG image: + +```bash +pygerber gerber convert png "my_gerber_file.gbr" -o "output.png" +``` + +For raster images it is possible to include a `-d`/`--dpmm` parameter to alter the pixel +per millimeter density of output image. Default value can be too big for some PCBs and +to small for others, so keep in mind that it may be necessary to adjust it. + +For vector images, you can convert Gerber files to SVG format: + +```bash +pygerber gerber convert svg "my_gerber_file.gbr" -o "output.svg" +``` + +Technically each conversion command supports selection of implementation of the +rendering engine, but currently there is only one raster and one vector engine +available. + +!!! note + + PyGerber is open for contributions, both regarding new output image formats as well as + new rendering engines. If you have an idea for a new feature, feel free to open an + issue on [GitHub](https://github.com/Argmaster/pygerber/issues/new/choose) or even + better, submit a [pull request](https://github.com/Argmaster/pygerber/compare)! + +## Formatting + +PyGerber offers a tool to format Gerber files. This tool can be used to reformat Gerber +files to make them more readable or the opposite, to compress them to save precious disk +space. Technically, formatter includes also minor code modernization features although +less powerful than the Optimizer. + +Let's have a look at an example of how one could format a Gerber file: + +```bash +pygerber gerber format "my_gerber_file.gbr" -o "output.gbr" +``` + +Quite simple, isn't it? You can customize how file will be formatted (default settings +are really basic) by providing either inline configuration in JSON format or by using a +configuration file (also in JSON format). + +Here is a simple example of how you could adjust indentation of macro bodies to 4 +spaces: + +```bash +pygerber gerber format src/pygerber/examples/carte_test-B_Cu.gbr -o formatted.gbr -i '{\"macro_body_indent\": 4}' +``` + +For more information about available configuration options, please refer to the +reference of `Options` class in +[here](../../reference/pygerber/gerber/formatter/options.md).