Improve 'Quick start' guide

Argmaster · Sep 30, 2024 · ac989b5 · ac989b5
1 parent a2ed980
commit ac989b5
Show file tree

Hide file tree

Showing 5 changed files with 90 additions and 53 deletions.
diff --git a/README.md b/README.md
@@ -30,15 +30,15 @@ It is based on Ucamco's `The Gerber Layer Format Specification. Revision 2024.05
 (Available on
 [Ucamco's webpage](https://www.ucamco.com/files/downloads/file_en/456/gerber-layer-format-specification-revision-2024-05_en.pdf).
 
-PyGerber can be used both as a executable with use of its command line interface and as
-a Python library.
+PyGerber can be used both as a executable (with command line interface) and as a Python
+library.
 
-PyGerber supports modern solutions available in the latest version of the standard
-(2024.05). At the same time, it includes the implementation of most outdated and
-selected removed functionalities. This allows it to be used not only with files
-compliant with the X3 standard but also with those compliant with X2, RS-274X, and
-RS-274D. Due to limited access to files in older standards and ambiguities within them,
-there is a risk that some older functionalities may behave incorrectly.
+PyGerber supports modern features available in the latest version of the standard
+(2024.05). At the same time, it includes the implementation of many of outdated and
+removed functionalities for backwards compatibility. This allows it to be used not only
+with files compliant with the X3 standard but also with those compliant with X2,
+RS-274X, and RS-274D. Due to limited access to files in older standards and ambiguities
+within them, there is a risk that some older functionalities may behave incorrectly.
 
 If you have found a bug in the PyGerber library, please report it in the
 [Issues](https://github.com/Argmaster/pygerber/issues/new/choose) section of our
@@ -75,8 +75,8 @@ pip install git+https://github.com/Argmaster/pygerber
 ## 📚 Documentation
 
 PyGerber has a online documentation hosted on Github Pages. It will be a great starting
-point for your journey with PyGerber. You can find documentation here
-[here](https://argmaster.github.io/pygerber/latest). If you are looking for
+point for your journey with PyGerber.
+[You can it here](https://argmaster.github.io/pygerber/latest). If you are looking for
 documentation of older version of PyGerber, please use version selector dropdown
 available next to the title in top bar menu.
 

diff --git a/docs/70_gerber/20_quick_start/01_single_file.md b/docs/70_gerber/20_quick_start/01_single_file.md
@@ -7,23 +7,23 @@ individual Gerber files.
 
 To perform any operations on Gerber file(s), like rendering or formatting, you have to
 create
-[`GerberFile`](./20_pygerber_gerber_api_reference.md#pygerber.gerber.api.GerberFile)
+[`GerberFile`](../../reference/pygerber/gerber/api/__init__.md#pygerber.gerber.api.GerberFile)
 class instance wrapping actual Gerber code. Recommended way is to use one of 3 factory
 methods provided by `GerberFile` class: `from_str()`, `from_file()` or `from_buffer()`
 
 `from_str()` creates `GerberFile` from `str` object containing Gerber code.
 
-{{ include_code("test/examples/gerberx3/api/_60_quick_start_from_str.quickstart.py", "python", title="example_from_str.py", linenums="1", hl_lines="12") }}
+{{ include_code("test/examples/gerberx3/api/_60_quick_start_from_str.quickstart.py", "docspygerberlexer", title="example_from_str.py", linenums="1", hl_lines="12") }}
 
 `from_file()` creates `GerberFile` by reading a file which location is determined by
 first parameter passed to `from_file()`. You can use `str` or `pathlib.Path` to specify
 file location.
 
-{{ include_code("test/examples/gerberx3/api/_61_quick_start_from_file.quickstart.py", "python", title="example_from_file.py", linenums="1", hl_lines="6") }}
+{{ include_code("test/examples/gerberx3/api/_61_quick_start_from_file.quickstart.py", "docspygerberlexer", title="example_from_file.py", linenums="1", hl_lines="6") }}
 
 `from_buffer()` creates `GerberFile` from `io.TextIO`-like object.
 
-{{ include_code("test/examples/gerberx3/api/_62_quick_start_from_buffer.quickstart.py", "python", title="example_from_buffer.py", linenums="1", hl_lines="5") }}
+{{ include_code("test/examples/gerberx3/api/_62_quick_start_from_buffer.quickstart.py", "docspygerberlexer", title="example_from_buffer.py", linenums="1", hl_lines="5") }}
 
 ## Configuring `GerberFile` object
 
@@ -32,41 +32,44 @@ methods on this object. `GerberFile` allows you to customize behavior of some of
 underlying implementation parts. Those methods mutate `GerberFile` object and
 consecutive calls to those methods override previous configuration in its **entirety**.
 
-`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 intentionally
-not precisely defined here, as they are different for different parser implementations,
-only way to use this method is to understand what you are doing.
+[`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
+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.
 
 `TODO: Add example`
 
-`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 understand what you are 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.
 
 `TODO: Add example`
 
-`set_color_map()` can be used to override default color map.
+[`set_color_map()`](../../reference/pygerber/gerber/api/__init__.md#pygerber.gerber.api.GerberFile.set_color_map)
+can be used to override default color map.
 
 Color map is used to map file type to predefined color style. PyGerber provides simple
 color schema but it is useful mostly for final renders as colors used were chosen to
 resemble final look of average PCB. Therefore you can easily provide your own color map.
 
 `TODO: Add example`
 
-Check out [Custom color maps](../10_custom_color_maps.md) for more details.
+Check out [Custom color maps](./10_custom_color_maps.md) for more details.
 
 ## Rendering Gerber file
 
 `GerberFile` object exposes
-[`render_with_pillow()`](../../reference/pygerber/gerber/api/__init__.html#pygerber.gerber.api.GerberFile.render_with_pillow)
+[`render_with_pillow()`](../../reference/pygerber/gerber/api/__init__.md#pygerber.gerber.api.GerberFile.render_with_pillow)
 method which renders Gerber file into Pillow image object.
 
-{{ include_code("test/examples/gerberx3/api/_00_single_file_render_with_pillow_defaults_str.example.py", "python", title="render_with_pillow.py", linenums="1") }}
+{{ include_code("test/examples/gerberx3/api/_00_single_file_render_with_pillow_defaults_str.example.py", "docspygerberlexer", title="render_with_pillow.py", linenums="1") }}
 
 `render_with_pillow()` method accepts `dpmm` parameter which can be used to set custom
 dots-per-millimeter value, hence increase and decrease image resolution. By default this
@@ -77,7 +80,7 @@ value is set to 20, which is a safe default, but quite low for small PCBs.
 
 To retrieve image object, you can use `get_image()` method. Afterwards you can save it
 with
-[`save()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.save)
+[`save()`](https://pillow.readthedocs.io/en/stable/reference/Image.md#PIL.Image.Image.save)
 method offered by `PIL.Image.Image` class instance or transform with other methods. To
 find out more please refer to
 [Pillow documentation](https://pillow.readthedocs.io/en/stable/).
@@ -86,27 +89,27 @@ To retrieve information about image space you can use `get_image_space()` method
 method returns `ImageSpace` object which contains information about image coordinates,
 image size, etc, as presented below:
 
-{{ include_code("test/examples/gerberx3/api/_50_show_image_info.singlefile.py", "python", title="show_image_space.py", linenums="1") }}
+{{ include_code("test/examples/gerberx3/api/_50_show_image_info.singlefile.py", "docspygerberlexer", title="show_image_space.py", linenums="1") }}
 
 {{ run_capture_stdout("python test/examples/gerberx3/api/_50_show_image_info.singlefile.py", "python show_image_space.py") }}
 
 ## Formatting Gerber file
 
 `GerberFile` object exposes
-[`format()`](../../reference/pygerber/gerber/api/__init__.html#pygerber.gerber.api.GerberFile.format)
+[`format()`](../../reference/pygerber/gerber/api/__init__.md#pygerber.gerber.api.GerberFile.format)
 and
-[`formats()`](../../reference/pygerber/gerber/api/__init__.html#pygerber.gerber.api.GerberFile.formats)
+[`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).
 
 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.
 
-{{ include_code("test/examples/gerberx3/api/_51_single_file_format.singlefile.py", "python", title="format_file.py", linenums="1") }}
+{{ include_code("test/examples/gerberx3/api/_51_single_file_format.singlefile.py", "docspygerberlexer", title="format_file.py", linenums="1") }}
 
 {{ run_capture_stdout("python test/examples/gerberx3/api/_51_single_file_format.singlefile.py", "python format_file.py", "gerber") }}
 
-## Further resources
+## Further reading
 
 Check out full reference of
 [`pygerber.gerber.api`](../../reference/pygerber/gerber/api/__init__.md).

diff --git a/docs/70_gerber/20_quick_start/02_multi_file_project.md b/docs/70_gerber/20_quick_start/02_multi_file_project.md
@@ -1,34 +1,46 @@
 # Multi file project guide
 
 This guide shows how to use `Project` class in par with `GerberFile` class to render
-multiple Gerber files into single, aligned image. Both classes can be imported from
-`pygerber.gerber.api`. For overview of `pygerber.gerber.api` module check out
-[Introduction](./00_introduction.md). For guide on how to operate on individual Gerber
-files and create `GerberFile` class instances, check out
-[Single file guide](./01_single_file.md).
-
-For full reference of `pygerber.gerber.api` module check out
-[Reference](./20_pygerber_gerber_api_reference.md)
+multiple Gerber files into single, aligned image.
 
 ## Creating Project instance
 
-`Project` class is a simple wrapper around multiple `GerberFile` objects. It
-automatically aligns all images and determines how big final image has to be to fit all
-images and merges them into single image. It is still possible to retrieve individual
-images from result returned by rendering methods.
+[`Project`](../../reference/pygerber/gerber/api/__init__.md#pygerber.gerber.api.Project)
+class is a simple wrapper around multiple
+[`GerberFile`](../../reference/pygerber/gerber/api/__init__.md#pygerber.gerber.api.GerberFile)
+objects. It automatically aligns all images and determines how big final image has to be
+to fit all images and merges them into single image. It is still possible to retrieve
+individual images from result returned by rendering methods.
 
 To create `Project` object you can use `Project` constructor. It accepts list of
-`GerberFile` objects as its only parameter. You can add more files to project by using
-`add_file()` method.
+`GerberFile` objects as its only parameter.
 
-{{ include_code("test/examples/gerberx3/api/_70_project_constructor_showcase.project.py", "python", title="create_project.py", linenums="1") }}
+{{ include_code("test/examples/gerberx3/api/_70_project_constructor_showcase.project.py", "docspygerberlexer", title="create_project.py", linenums="1") }}
 
 {{ run_capture_stdout("python test/examples/gerberx3/api/_70_project_constructor_showcase.project.py", "python create_project.py") }}
 
 ## Rendering Project
 
-{{ include_code("test/examples/gerberx3/api/_71_project_render_with_pillow.example.py", "python", title="render_project.py", linenums="1") }}
+Rendering `Project` object is similar to rendering `GerberFile` object. `Project` object
+exposes `render_with_pillow()` method which renders all files into single image.
+
+{{ include_code("test/examples/gerberx3/api/_71_project_render_with_pillow.example.py", "docspygerberlexer", title="render_project.py", linenums="1") }}
 
 <p align="center">
     <img src="render_project.png" alt="render_project" width="300" />
 </p>
+
+## Accessing individual images
+
+After rendering `Project` object you can access individual images by using
+[`get_sub_images()`](../../reference/pygerber/gerber/api/__init__.md#pygerber.gerber.api.CompositeImage.get_sub_images)
+of
+[`CompositeImage`](../../reference/pygerber/gerber/api/__init__.md#pygerber.gerber.api.CompositeImage)
+object returned by `render_with_pillow()` method.
+
+`TODO: Add example`
+
+## Further reading
+
+Check out full reference of
+[`pygerber.gerber.api`](../../reference/pygerber/gerber/api/__init__.md).
diff --git a/src/pygerber/gerber/api/__init__.py b/src/pygerber/gerber/api/__init__.py
@@ -16,7 +16,7 @@
     PillowImage,
     Units,
 )
-from pygerber.gerber.api._project import Project
+from pygerber.gerber.api._project import CompositeImage, Project
 from pygerber.gerber.formatter.options import Options
 
 __all__ = [
@@ -27,6 +27,7 @@
     "ImageSpace",
     "Image",
     "PillowImage",
+    "CompositeImage",
     "DEFAULT_COLOR_MAP",
     "DEFAULT_ALPHA_COLOR_MAP",
     "Options",

diff --git a/src/pygerber/gerber/pygments.py b/src/pygerber/gerber/pygments.py
@@ -149,6 +149,27 @@ class PyGerberDocsLexer(PythonLexer):
             **{  # noqa: PIE800
                 "TraceDraw": Name.Class,
             },
+            **{  # noqa: PIE800
+                "GerberFile": Name.Class,
+                "from_str": Name.Function,
+                "from_file": Name.Function,
+                "from_buffer": Name.Function,
+                "render_with_pillow": Name.Function,
+                "format": Name.Function,
+                "formats": Name.Function,
+                "get_image": Name.Function,
+            },
+            **{  # noqa: PIE800
+                "Project": Name.Class,
+                "render_with_pillow": Name.Function,
+                "get_image": Name.Function,
+                "get_sub_images": Name.Function,
+            },
+            **{  # noqa: PIE800
+                "FileTypeEnum": Name.Class,
+            },
+            "ExamplesEnum": Name.Class,
+            "load_example": Name.Function,
         }
 
         def get_tokens_unprocessed(self, text: Any) -> Any: