Update documentation

docs/40_gerber/00_introduction.md

@@ -1,4 +1,4 @@
-# Introduction
+# 🧭 Introduction
 
 ## What you will find here
 

docs/40_gerber/10_migrate_from_2_4_x_to_3_x_x.md

@@ -1,4 +1,4 @@
-# Migrating from 2.4.x to 3.x.x
+# 🤧 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

docs/40_gerber/20_quick_start/00_introduction.md

@@ -1,4 +1,4 @@
-# Introduction
+# 🧭 Introduction
 
 ## Overview
 

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

@@ -1,4 +1,4 @@
-# Single file guide
+# 🥐 Single file guide
 
 Welcome to the PyGerber single file guide. This guide focuses on tools which take single
 Gerber file as opposed to [Multi file guide](./02_multi_file.md) guide which is

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

@@ -1,4 +1,4 @@
-# Multi file guide
+# 🥞 Multi file guide
 
 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`

docs/40_gerber/20_quick_start/03_project_gerber_job.md

@@ -1,4 +1,4 @@
-# GerberJobFile and Project
+# 🥧 GerberJobFile and Project
 
 This guide shows how to use `GerberJobFile` class and `Project` to represent PCB
 projects.

docs/40_gerber/20_quick_start/10_custom_color_maps.md

@@ -1,4 +1,4 @@
-# Custom color maps
+# 🧁 Custom color maps
 
 ## Introduction
 

docs/40_gerber/30_analysis/00_introduction.md

@@ -1,4 +1,4 @@
-# Introduction
+# 🧭 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

docs/40_gerber/30_analysis/10_stateless_introspection.md

@@ -1,4 +1,4 @@
-# Stateless Introspection
+# 🧪 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!

docs/40_gerber/30_analysis/20_stateful_introspection.md

@@ -1,4 +1,4 @@
-# Stateful Introspection
+# 🧬 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!

docs/40_gerber/40_modify_optimize/00_introduction.md

@@ -1,4 +1,4 @@
-# Introduction
+# 🧭 Introduction
 
 Welcome to the Gerber Optimizer documentation. This documentation is intended to provide
 a comprehensive overview of the Gerber Optimizer including usage, options and examples.

docs/40_gerber/40_modify_optimize/30_code_optimization.md

@@ -1,4 +1,4 @@
-# Code optimization
+# 🧴 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!

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

@@ -1,4 +1,4 @@
-# Introduction
+# 🧭 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.

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

@@ -1,4 +1,4 @@
-# API usage
+# ☕ API usage
 
 The Gerber Formatter can be used as a library. The main entry point is the
 `pygerber.gerber.formatter` module.

docs/40_gerber/60_formatter/20_extending_formatter.md

@@ -1 +1 @@
-# Extending Formatter
+# 🥠 Extending Formatter

docs/40_gerber/70_diagnostics/00_introduction.md

@@ -1,4 +1,26 @@
-# Introduction
+# 🧭 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!
+## Overview
+
+PyGerber provides a linter (diagnostic tool) for analyzing Gerber code. The linter is a
+tool that focuses on checking the code itself, not the design of the PCB. Therefore it
+includes checks for deprecated features, common deviations from Gerber standard and
+other Gerber focused checks, but does not contain any check that verify the quality of
+the PCB design, like connectivity, trace width, etc.
+
+The Gerber linter is a tool that has limited usefulness for the average user, but can be
+very handy for verifying the quality of generated Gerber code, especially while working
+on solutions that modify or generate Gerber code, to ensure compliance with latest
+Gerber standard.
+
+## API
+
+Gerber linter API is available in the `pygerber.gerber.linter` module. Simplified
+interface consists of a single function `lint` that takes a Gerber AST as input and
+returns a list of rule violations detected in AST.
+
+Here is a simple example of how to use the linter:
+
+{{ include_code("test/examples/gerberx3/linter/_00_linter.example.py", "docspygerberlexer", title="custom_color_map.py", linenums="1") }}
+
+{{ run_capture_stdout("python test/examples/gerberx3/linter/_00_linter.example.py", "python example.py") }}

docs/40_gerber/70_diagnostics/01_rule_list.md

@@ -0,0 +1,6 @@
+# 📄 Rule list
+
+Below you can find full list of all rules implemented in PyGerber for Gerber format
+diagnostics.
+
+{{ gerber_linter_rule_list() }}

docs/40_gerber/80_language_server/00_introduction.md

@@ -1,4 +1,4 @@
-# Introduction
+# 🧭 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!

docs/40_gerber/80_language_server/10_vsc_integration.md

@@ -1,4 +1,4 @@
-# Visual Studio Code Integration
+# 🥨 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!

docs/40_gerber/80_language_server/50_features.md

@@ -1,4 +1,4 @@
-# Features
+# 🧰 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!

docs/40_gerber/90_extend/00_introduction.md

@@ -1,4 +1,4 @@
-# Introduction
+# 🧭 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!

docs/40_gerber/90_extend/40_extending_ast_nodes.md

@@ -1,4 +1,4 @@
-# Extending AST Nodes
+# 🥥 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!

docs/40_gerber/90_extend/50_extending_parser.md

@@ -1 +1,4 @@
-# Extending Parser
+# 🧽 Extending Parser
+
+Unfortunately, this documentation is yet to be written. I am doing my best to provide it
+before release 3.0.0 so stay tuned!

docs/40_gerber/90_extend/60_extending_compiler.md

@@ -1 +1,4 @@
-# Extending Compiler
+# 🧶 Extending Compiler
+
+Unfortunately, this documentation is yet to be written. I am doing my best to provide it
+before release 3.0.0 so stay tuned!

docs/40_gerber/90_extend/70_extending_virtual_machines.md

@@ -1 +1,4 @@
-# Extending Virtual Machines
+# 🧩 Extending Virtual Machines
+
+Unfortunately, this documentation is yet to be written. I am doing my best to provide it
+before release 3.0.0 so stay tuned!

docs/50_command_line/00_introduction.md

@@ -1,4 +1,4 @@
-# Introduction
+# 🧭 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.

docs/50_command_line/20_gerber.md

@@ -1,4 +1,4 @@
-# Gerber
+# 🥞 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

docs/60_rendering_backends/00_introduction.md

@@ -1 +1 @@
-# Introduction
+# 🧭 Introduction

docs/80_code_generation/00_introduction.md

@@ -1 +1,15 @@
-# Introduction
+# 🧭 Introduction
+
+## Overview
+
+Welcome to the documentation of the code generation feature of PyGerber library!
+Considering that to develop PyGerber core functionality of parsing Gerber files it was
+necessary to design a lot of tools to verify the correctness of the implementation, it
+became apparent that is will be much easier to compliment existing tool set with a code
+generation tools rather than develop separate package for that purpose. Therefore, the
+decision was made to develop a code generation feature as a part of PyGerber library.
+
+Currently, there are two code generation APIs, one for generation of Gerber code and the
+second one for generation of RVMC code (internal geometry representation used by
+PyGerber). Those APIs are available in the `pygerber.builder.gerber` and
+`pygerber.builder.rvmc` respectively.

docs/90_development/00_introduction.md

@@ -1 +1,7 @@
-# Introduction
+# 🧭 Introduction
+
+## Overview
+
+Welcome to collection of development related guides for PyGerber project. Those guides
+will be helpful if you are considering contributing to the project or if you want to
+review the code in more detail.

docs/macros/main.py

@@ -91,6 +91,21 @@ def run_render_gerber_from_stdout(command: str, dpmm: int) -> str:
 
         return _base64_image_tag(out.get_image())
 
+    @env.macro
+    def gerber_linter_rule_list() -> str:
+        """Generate markdown of list of rules used by the Gerber linter."""
+        from pygerber.gerber.linter import RULE_REGISTRY
+
+        def _():
+            for rule_type in RULE_REGISTRY.values():
+                rule = rule_type()
+                yield (
+                    f"---\n## {rule.rule_id}\n\n{rule.get_violation_title()}\n\n"
+                    f"{rule.get_violation_description()}\n"
+                )
+
+        return "\n".join(_())
+
 
 def _base64_image_tag(image: Image.Image) -> str:
     buffered = io.BytesIO()

src/pygerber/console/gerber.py

@@ -531,6 +531,9 @@ def _project(files: str, output: str, dpmm: int) -> None:
 )
 def lint(files: str, rules: list[str]) -> None:
     """Lint Gerber files with specified rules."""
+    from pygerber.gerber.linter import lint
+    from pygerber.gerber.parser import parse
+
     if len(files) == 0:
         msg = "At least one file must be specified."
         raise click.UsageError(msg)
@@ -539,21 +542,13 @@ def _parse_rules(rules: list[str]) -> Iterable[str]:
         for rule in rules:
             yield from rule.split(",")
 
-    from pygerber.gerber.linter import RULE_REGISTRY, Linter
-    from pygerber.gerber.parser import parse
-
-    if len(rules) != 0:
-        rule_objects = [RULE_REGISTRY[rule_id]() for rule_id in _parse_rules(rules)]
-    else:
-        rule_objects = [r() for r in RULE_REGISTRY.values()]
-
-    linter = Linter(rule_objects)
+    rules = list(_parse_rules(rules))
 
     for file in files:
         path = Path(file).expanduser().resolve()
 
         ast = parse(path.read_text())
-        violations = linter.lint(ast)
+        violations = lint(ast, rules=rules)
 
         for violation in violations:
             click.echo(

src/pygerber/examples/__init__.py

@@ -29,6 +29,8 @@ class ExamplesEnum(Enum):
 
     carte_test_gbrjob = "carte_test-job.gbrjob"
 
+    fc_poly_b_cu = "fc_poly_b_cu.grb"
+
 
 DIRECTORY = Path(__file__).parent