Extend documentation

Argmaster · Nov 24, 2024 · bc0526c · bc0526c
1 parent 488962b
commit bc0526c
Show file tree

Hide file tree

Showing 19 changed files with 169 additions and 20 deletions.
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
@@ -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
@@ -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
diff --git a/docs/40_gerber/25_command_line/20_gerber.md b/docs/40_gerber/25_command_line/20_gerber.md
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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).