Update documentation

docs/40_gerber/20_quick_start/01_single_file.md

@@ -6,6 +6,10 @@ concerned with operating on collections of Gerber files. Most of the functionali
 exposed as methods on `GerberFile` class which can be imported from
 `pygerber.gerber.api` module and we will be using it throughout this document.
 
+Currently `GerberFile` class provides means to render Gerber files into raster and
+vector image formats and format Gerber code. Code optimization, cleanup and diagnostics
+are on the roadmap.
+
 ## Creating `GerberFile` instance
 
 To perform any operations on individual Gerber file(s), like rendering or formatting,
@@ -158,7 +162,7 @@ maps see [Custom color maps](./10_custom_color_maps.md).
 and
 [`formats()`](../../reference/pygerber/gerber/api/__init__.md#pygerber.gerber.api.GerberFile.formats)
 methods which format Gerber code. For detailed documentation of formatting options,
-please refer to [Formatter -> Configuration](../60_formatter/10_configuration.md).
+please refer to [Formatter -> Configuration](../60_formatter/05_api_usage.md#).
 
 The difference between `format()` and `formats()` methods is that first one writes
 formatted code to `TextIO`-like object while second one returns it as a `str` object.

docs/40_gerber/20_quick_start/02_multi_file.md

@@ -1,23 +1,31 @@
 # Multi file guide
 
-This guide shows how to use `CompositeView` class in par with `GerberFile` class to
-operate on multiple Gerber files at once.
+Welcome to the multi file guide. This guide shows how to use `CompositeView` class API
+to handle multiple Gerber files at once. `CompositeView` relies on `GerberFile`
+instances to provide access to individual Gerber files, hence It might be useful if you
+take a look onto [Single file guide](./01_single_file.md) before continuing with this
+guide.
 
 ## Creating `CompositeView` instance
 
 [`CompositeView`](../../reference/pygerber/gerber/api/__init__.md#pygerber.gerber.api.CompositeView)
 class is a thin wrapper around multiple
 [`GerberFile`](../../reference/pygerber/gerber/api/__init__.md#pygerber.gerber.api.GerberFile)
-objects. Usually it does not make sense to operate on all files from project at once,
-since rendering **top** layers on top of **bottom** ones will produce hard to understand
-images. It makes more sense to render them separately. Therefore `CompositeView` is a
-way to group files that should be rendered together, for example all parts of **top** of
-PCB, silkscreen, solder mask, top copper etc. while parts of **bottom** of PCB are
-grouped in separate `CompositeView`, so do internal layers.
-
-`CompositeView` constructor accepts multiple `GerberFile` objects as arguments. First
-`GerberFile` is the bottom most, usually copper layer, and last `GerberFile` is top
-most, usually silk screen. Here is an example:
+objects which can be imported from `pygerber.gerber.api` module. You may have noticed
+that the name of the class is weirdly generic, instead of being something like Project
+or alike. Well, it turns out that usually it does not make sense to operate on all files
+from project at once, for example, rendering **top** layers on top of **bottom** ones
+will produce hard to understand images. Therefore PyGerbers `CompositeView` class takes
+an aproach of group files that should be rendered together instead of accumulating all
+the files from the project. With that logic in mind, we would use one instance of
+`CompositeView` to represent top layer of the design, with silkscreen, solder mask, top
+copper etc. while parts of **bottom** of PCB are grouped in separate `CompositeView`
+instance.
+
+`CompositeView` constructor accepts multiple `GerberFile` objects as arguments. Order of
+files affects order of rendering to shared image. First `GerberFile` is the bottom most,
+usually copper layer, will be covered with all other layers, and last `GerberFile` is
+top most, usually silk screen, will not be obscured by any layer. Here is an example:
 
 {{ include_code("test/examples/gerberx3/api/_70_multi_file_constructor_showcase.project.py", "docspygerberlexer", title="create_project.py", linenums="1") }}
 

docs/40_gerber/60_formatter/00_introduction.md

@@ -1 +1,33 @@
 # Introduction
+
+Welcome to the Gerber Formatter documentation. This documentation is intended to provide
+a comprehensive overview of the Gerber Formatter including usage, options and examples.
+
+!!! info
+
+    Please note that this API is lower-level than one offered by the `GerberFile` object you
+    can find [here](../20_quick_start/01_single_file.md). In many cases `GerberFile`
+    interface will be more intuitive and easier to use, hence it is usually better to stick
+    with it unless you have specific needs that are not covered by it.
+
+## What is the Gerber Formatter?
+
+The Gerber Formatter is a tool that can be used to format Gerber files. It 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.
+
+## Why?
+
+Gerber files are often used just as transfer format and rarely it is necessary to read
+them directly. However, in those rare cases when you have to look into them, it would be
+nice for them to be more readable than what your CAD software of choice happens to spit
+out. This is where the Gerber Formatter comes in handy.
+
+## How?
+
+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
+API usage and configuration options are covered in [API usage](./05_api_usage.md).

docs/40_gerber/60_formatter/05_api_usage.md

@@ -0,0 +1,25 @@
+# API usage
+
+The Gerber Formatter can be used as a library. The main entry point is the
+`pygerber.gerber.formatter` module.
+
+## API
+
+The basic usage of the Gerber Formatter is to utilize `format` and `formats` functions
+available in `pygerber.gerber.formatter` module. Please have look at the following
+example:
+
+{{ include_code("test/examples/gerberx3/formatter/_10_basic_format.py", "docspygerberlexer", title="format_example.py", linenums="1") }}
+
+Please note that to format the code, we first had to parse it, and only then could the
+abstract syntax tree be passed to the formatter. `format` function writes formatted code
+directly to file-like object, while `formats` function returns formatted code as a
+string.
+
+## Configuration
+
+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).
+
+{{ include_code("test/examples/gerberx3/formatter/_20_format_with_options.py", "docspygerberlexer", title="options_example.py", linenums="1") }}

src/pygerber/gerber/formatter/options.py

@@ -22,8 +22,6 @@
 class Options(BaseModel):
     """The `Options` class aggregates configuration options for the Gerber
     formatter.
-
-    For detailed description of individual options, please visit (TODO: Add doc link).
     """
 
     indent_character: Literal[" ", "\t"] = Field(default=" ")

test/examples/gerberx3/formatter/_10_basic_format.py

@@ -0,0 +1,11 @@
+from pathlib import Path
+from pygerber.gerber.parser import parse
+from pygerber.gerber.formatter import format
+from pygerber.examples import ExamplesEnum, load_example
+
+gerber_source_code = load_example(ExamplesEnum.UCAMCO_2_11_2)
+
+ast = parse(gerber_source_code)
+
+with Path("output.formatted.gbr").open("w") as output:
+    format(ast, output)

test/examples/gerberx3/formatter/_11_basic_formats.py

@@ -0,0 +1,9 @@
+from pygerber.gerber.parser import parse
+from pygerber.gerber.formatter import formats
+from pygerber.examples import ExamplesEnum, load_example
+
+gerber_source_code = load_example(ExamplesEnum.UCAMCO_2_11_2)
+
+ast = parse(gerber_source_code)
+
+print(formats(ast))

test/examples/gerberx3/formatter/_20_format_with_options.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+from pygerber.gerber.parser import parse
+from pygerber.gerber.formatter import format, Options, MacroSplitMode
+from pygerber.examples import ExamplesEnum, load_example
+
+gerber_source_code = load_example(ExamplesEnum.UCAMCO_2_11_2)
+
+ast = parse(gerber_source_code)
+
+with Path("output.formatted.gbr").open("w") as output:
+    format(
+        ast,
+        output,
+        options=Options(
+            indent_character="\t",
+            macro_split_mode=MacroSplitMode.NoSplit,
+        ),
+    )