Add GerberFile creation docs

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

@@ -15,4 +15,42 @@ interfaces.
 
 PyGerber exposes a simple API for accessing limited subset of its functionalities in
 form of `pygerber.gerber.api` module. This interface is especially useful for one time
-use, scripting and use from interactive shell.
+use, scripting and use from interactive shell. Most of the functionality has been
+included in the GerberFile class and Project class. Additionally, there is a
+FileTypeEnum containing recognized file types and few error classes.
+
+## Creating `GerberFile` object
+
+To perform any operations on Gerber file, like rendering or formatting, you have to
+create `GerberFile` object wrapping actual Gerber code. Recommended way is to use one of
+3 factory methods provided by GerberFile class.
+
+To create `GerberFile` from `str` object you can use
+[`GerberFile.from_str`](./20_gerber_file.md#pygerber.gerber.api.GerberFile.from_str)
+factory method. It accepts up to two arguments. First one is mandatory `source_code` and
+you should pass Gerber code `str` object to it. Second one is optional and can be used
+to manually set file type (eg. silk screen, copper, drill etc.). If second argument is
+not provided, default behavior is to try to guess file type based on file extension or
+file attributes. Method returns `GerberFile` instance.
+
+{{ include_code("test/examples/gerberx3/api/_90_quick_start_from_str.py", "python", title="example_from_str.py", linenums="1", hl_lines="12") }}
+
+Alternatively you can create `GerberFile` object from file using
+[`GerberFile.from_file`](./20_gerber_file.md#pygerber.gerber.api.GerberFile.from_file)
+factory method. It accepts up to two arguments. First one is mandatory `file_path` which
+has to be a path to existing file, either as `str` or `pathlib.Path` objec. Second one
+is optional and can be used to manually set file type (eg. silk screen, copper, drill
+etc.). If second argument is not provided, default behavior is to try to guess file type
+based on file extension or file attributes. Method returns `GerberFile` instance.
+
+{{ include_code("test/examples/gerberx3/api/_91_quick_start_from_file.py", "python", title="example_from_file.py", linenums="1", hl_lines="6") }}
+
+Last way to create `GerberFile` object is to use
+[`GerberFile.from_buffer`](./20_gerber_file.md#pygerber.gerber.api.GerberFile.from_buffer)
+factory method. It accepts up to two arguments. First one is mandatory `buffer` which
+has to be a `StringIO`-like object supporting `read()` method. Second one is optional
+and can be used to manually set file type (eg. silk screen, copper, drill etc.). If
+second argument is not provided, default behavior is to try to guess file type based on
+file extension or file attributes. Method returns `GerberFile` instance.
+
+{{ include_code("test/examples/gerberx3/api/_92_quick_start_from_buffer.py", "python", title="example_from_buffer.py", linenums="1", hl_lines="5") }}

docs/70_gerber/20_quick_start/20_gerber_file.md

@@ -0,0 +1,3 @@
+# GerberFile class
+
+::: pygerber.gerber.api.GerberFile

docs/macros/main.py

@@ -13,7 +13,7 @@ def define_env(env: MacrosPlugin) -> None:
     """
 
     @env.macro
-    def include_file(filename, start_line=0, end_line=None):  # type: ignore[no-untyped-def]
+    def include_file(filename: str, start_line=0, end_line=None):  # type: ignore[no-untyped-def]
         """Include a file, optionally indicating start_line and end_line
         (start counting from 0)
         The path is relative to the top directory of the documentation
@@ -24,3 +24,21 @@ def include_file(filename, start_line=0, end_line=None):  # type: ignore[no-unty
             lines = f.readlines()
         line_range = lines[start_line:end_line]
         return "".join(line_range)
+
+    @env.macro
+    def include_code(
+        filename: str, language: str, start_line=0, end_line=None, **options: str
+    ):
+        """Include a file, optionally indicating start_line and end_line
+        (start counting from 0)
+        The path is relative to the top directory of the documentation
+        project.
+        """
+        full_filename = os.path.join(env.project_dir, filename)
+        with open(full_filename) as f:
+            lines = f.readlines()
+        line_range = lines[start_line:end_line]
+
+        options_str = " ".join(f'{k}="{v}"' for k, v in options.items())
+
+        return f"```{language} {options_str}\n" + "".join(line_range) + "```"

src/pygerber/gerber/api/_gerber_file.py

@@ -226,7 +226,21 @@ def from_str(
         source_code: str,
         file_type: FileTypeEnum = FileTypeEnum.INFER,
     ) -> Self:
-        """Initialize object with Gerber source code from string."""
+        """Initialize GerberFile object with Gerber source code from string.
+
+        Parameters
+        ----------
+        source_code : str
+            Gerber source code as `str`object.
+        file_type : FileTypeEnum, optional
+            File type classification, by default FileTypeEnum.INFER
+
+        Returns
+        -------
+        Self
+            _description_
+
+        """
         if file_type == FileTypeEnum.INFER_FROM_EXTENSION:
             file_type = FileTypeEnum.UNDEFINED
         return cls(source_code, file_type)

test/examples/gerberx3/api/_90_quick_start_from_str.py

@@ -0,0 +1,12 @@
+from pygerber.gerber.api import GerberFile
+
+source_code = """
+%FSLAX26Y26*%
+%MOMM*%
+%ADD100C,1.5*%
+D100*
+X0Y0D03*
+M02*
+"""
+
+gerber_file = GerberFile.from_str(source_code)

test/examples/gerberx3/api/_91_quick_start_from_file.py

@@ -0,0 +1,6 @@
+from pygerber.gerber.api import GerberFile
+from pathlib import Path
+
+path_to_my_gerber_file = Path().cwd() / "example.grb"
+
+gerber_file = GerberFile.from_file(path_to_my_gerber_file)

test/examples/gerberx3/api/_92_quick_start_from_buffer.py

@@ -0,0 +1,5 @@
+from pygerber.gerber.api import GerberFile
+from pathlib import Path
+
+with (Path().cwd() / "example.grb").open() as text_io:
+    gerber_file = GerberFile.from_buffer(text_io)