[KiKit Present] Added quick start support

- Also added mechanism to embed the markdown description
- Some adjusts to the help

README.md

@@ -2425,32 +2425,37 @@ Notes:
       * Valid keys:
         - **`description`**: [string=''] Name for a markdown file containing the main part of the page to be generated.
                              This is mandatory and is the description of your project.
+                             You can embed the markdown code. If the text doesn't map to a file and contains
+                             more than one line KiBot will assume this is the markdown.
         - `boards`: [dict|list(dict)] One or more boards that compose your project.
                     When empty we will use only the main PCB for the current project.
           * Valid keys:
-            - **`back_image`**: [string=''] local*: the name of an output that renders the back.
-                                If empty we use the first renderer for the back.
-                                *file*: the name of the rendered image.
-                                *external*: ignored, we `extrenal_config`.
-            - **`front_image`**: [string=''] local*: the name of an output that renders the front.
-                                 If empty we use the first renderer for the front.
-                                 *file*: the name of the rendered image.
-                                 *external*: ignored, we `extrenal_config`.
-            - **`gerbers`**: [string=''] local*: the name of a compress output.
-                             If empty we use the first compress output.
-                             *file*: the name of a compressed archive.
-                             *external*: ignored, we `extrenal_config`.
             - **`name`**: [string=''] Name for this board. If empty we use the name of the PCB.
                           Applies to all modes.
+            - `back_image`: [string=''] How to obtain the back view of the PCB.
+                            *local*: the name of an output to render it.
+                            If empty we use the first renderer.
+                            *file*: the name of the rendered image.
+                            *external*: ignored, we use `extrenal_config`.
             - `comment`: [string=''] A comment or description for this board.
                          Applies to all modes.
             - `external_config`: [string=''] Name of an external KiBot configuration.
                                  Only used in the *external* mode.
-            - `mode`: [string='auto'] [local,file,external] How images and gerbers are obtained.
+            - `front_image`: [string=''] How to obtain the front view of the PCB.
+                             *local*: the name of an output to render it.
+                             If empty we use the first renderer.
+                             *file*: the name of the rendered image.
+                             *external*: ignored, we use `extrenal_config`.
+            - `gerbers`: [string=''] How to obtain an archive with the gerbers.
+                         *local*: the name of a `gerber` output.
+                         If empty we use the first `gerber` output.
+                         *file*: the name of a compressed archive.
+                         *external*: ignored, we use `extrenal_config`.
+            - `mode`: [string='local'] [local,file,external] How images and gerbers are obtained.
                       *local*: Only applies to the currently selected PCB.
                       You must provide the names of the outputs used to render
                       the images and compress the gerbers.
-                      When empty KiBot will use the first render/compress output
+                      When empty KiBot will use the first render/gerber output
                       it finds.
                       To apply variants use `pcb_from_output` and a `pcb_variant`
                       output.

docs/samples/generic_plot.kibot.yaml

@@ -1193,10 +1193,11 @@ outputs:
       # [dict|list(dict)] One or more boards that compose your project.
       # When empty we will use only the main PCB for the current project
       boards:
-        # [string=''] local*: the name of an output that renders the back.
+        # [string=''] How to obtain the back view of the PCB.
-        # If empty we use the first renderer for the back.
+        # *local*: the name of an output to render it.
+        # If empty we use the first renderer.
         # *file*: the name of the rendered image.
-        # *external*: ignored, we `extrenal_config`
+        # *external*: ignored, we use `extrenal_config`
         - back_image: ''
           # [string=''] A comment or description for this board.
           # Applies to all modes
@@ -1204,21 +1205,23 @@ outputs:
           # [string=''] Name of an external KiBot configuration.
           # Only used in the *external* mode
           external_config: ''
-          # [string=''] local*: the name of an output that renders the front.
+          # [string=''] How to obtain the front view of the PCB.
-          # If empty we use the first renderer for the front.
+          # *local*: the name of an output to render it.
+          # If empty we use the first renderer.
           # *file*: the name of the rendered image.
-          # *external*: ignored, we `extrenal_config`
+          # *external*: ignored, we use `extrenal_config`
           front_image: ''
-          # [string=''] local*: the name of a compress output.
+          # [string=''] How to obtain an archive with the gerbers.
-          # If empty we use the first compress output.
+          # *local*: the name of a `gerber` output.
+          # If empty we use the first `gerber` output.
           # *file*: the name of a compressed archive.
-          # *external*: ignored, we `extrenal_config`
+          # *external*: ignored, we use `extrenal_config`
           gerbers: ''
-          # [string='auto'] [local,file,external] How images and gerbers are obtained.
+          # [string='local'] [local,file,external] How images and gerbers are obtained.
           # *local*: Only applies to the currently selected PCB.
           # You must provide the names of the outputs used to render
           # the images and compress the gerbers.
-          # When empty KiBot will use the first render/compress output
+          # When empty KiBot will use the first render/gerber output
           # it finds.
           # To apply variants use `pcb_from_output` and a `pcb_variant`
           # output.
@@ -1229,7 +1232,7 @@ outputs:
           # the gerbers. The front image must be generated in a dir called
           # *front*, the back image in a dir called *back* and the gerbers
           # in a dir called *gerbers*
-          mode: 'auto'
+          mode: 'local'
           # [string=''] Name for this board. If empty we use the name of the PCB.
           # Applies to all modes
           name: ''
@@ -1240,7 +1243,9 @@ outputs:
           # Is ignored for the *file* mode
           pcb_from_output: ''
       # [string=''] Name for a markdown file containing the main part of the page to be generated.
-      # This is mandatory and is the description of your project
+      # This is mandatory and is the description of your project.
+      # You can embed the markdown code. If the text doesn't map to a file and contains
+      # more than one line KiBot will assume this is the markdown
       description: ''
       # [string=''] Name of the project. Will be passed to the template.
       # If empty we use the name of the KiCad project.

kibot/out_kikit_present.py

@@ -17,10 +17,11 @@ import shutil
 import sys
 from tempfile import NamedTemporaryFile, TemporaryDirectory, mkdtemp
 from .error import KiPlotConfigurationError
-from .misc import W_PCBDRAW, RENDERERS, PCB_GENERATORS, W_MORERES
+from .misc import PCB_GENERATORS, RENDERERS, W_MORERES
 from .gs import GS
 from .kiplot import config_output, run_output, get_output_dir, load_board, run_command
 from .optionable import BaseOptions, Optionable
+from .out_base import BaseOutput
 from .registrable import RegOutput
 from .PcbDraw.present import boardpage, readTemplate
 from .macros import macros, document, output_class  # noqa: F401
@@ -30,10 +31,6 @@ from . import log
 logger = log.get_logger()
 
 
-def pcbdraw_warnings(tag, msg):
-    logger.warning('{}({}) {}'.format(W_PCBDRAW, tag, msg))
-
-
 def _get_tmp_name(ext):
     with NamedTemporaryFile(mode='w', suffix='.'+ext, delete=False) as f:
         f.close()
@@ -73,17 +70,20 @@ class PresentBoards(Optionable):
             """ Use the PCB generated by another output.
                 Is ignored for the *file* mode """
             self.front_image = ''
-            """ *local*: the name of an output that renders the front.
+            """ How to obtain the front view of the PCB.
-                If empty we use the first renderer for the front.
+                *local*: the name of an output to render it.
+                If empty we use the first renderer.
                 *file*: the name of the rendered image.
                 *external*: ignored, we use `extrenal_config` """
             self.back_image = ''
-            """ *local*: the name of an output that renders the back.
+            """ How to obtain the back view of the PCB.
-                If empty we use the first renderer for the back.
+                *local*: the name of an output to render it.
+                If empty we use the first renderer.
                 *file*: the name of the rendered image.
                 *external*: ignored, we use `extrenal_config` """
             self.gerbers = ''
-            """ *local*: the name of a `gerber` output.
+            """ How to obtain an archive with the gerbers.
+                *local*: the name of a `gerber` output.
                 If empty we use the first `gerber` output.
                 *file*: the name of a compressed archive.
                 *external*: ignored, we use `extrenal_config` """
@@ -279,7 +279,9 @@ class KiKit_PresentOptions(BaseOptions):
         with document:
             self.description = ''
             """ *Name for a markdown file containing the main part of the page to be generated.
-                This is mandatory and is the description of your project """
+                This is mandatory and is the description of your project.
+                You can embed the markdown code. If the text doesn't map to a file and contains
+                more than one line KiBot will assume this is the markdown """
             self.boards = PresentBoards
             """ [dict|list(dict)] One or more boards that compose your project.
                 When empty we will use only the main PCB for the current project """
@@ -304,7 +306,9 @@ class KiKit_PresentOptions(BaseOptions):
         if not self.description:
             raise KiPlotConfigurationError('You must specify an input markdown file using `description`')
         if not os.path.isfile(self.description):
-            raise KiPlotConfigurationError('Missing description file `{}`'.format(self.description))
+            self.description = self.description.split('\n')
+            if len(self.description) == 1:
+                raise KiPlotConfigurationError('Missing description file `{}`'.format(self.description))
         # List of boards
         if isinstance(self.boards, type):
             a_board = PresentBoards()
@@ -361,8 +365,16 @@ class KiKit_PresentOptions(BaseOptions):
         try:
             for brd in self.boards:
                 board.append(brd.solve(temporals))
+            # Support embedded markdown
+            if isinstance(self.description, list):
+                tmp_md = _get_tmp_name('md')
+                with open(tmp_md, 'w') as f:
+                    f.writelines([ln+'\n' for ln in self.description])
+                self._description = tmp_md
+            else:
+                self._description = self.description
             try:
-                boardpage(dir_name, self.description, board, self.resources, self.template, self.repository, self.name)
+                boardpage(dir_name, self._description, board, self.resources, self.template, self.repository, self.name)
             except RuntimeError as e:
                 raise KiPlotConfigurationError('KiKit present error: '+str(e))
         finally:
@@ -374,7 +386,7 @@ class KiKit_PresentOptions(BaseOptions):
 
 
 @output_class
-class KiKit_Present(BaseOutput):  # noqa: F821
+class KiKit_Present(BaseOutput):
     """ KiKit's Present - Project Presentation
         Creates an HTML file showing your project.
         It can contain one or more PCBs, showing their top and bottom sides.
@@ -385,3 +397,23 @@ class KiKit_Present(BaseOutput):  # noqa: F821
             self.options = KiKit_PresentOptions
             """ *[dict] Options for the `kikit_present` output """
         self._category = 'PCB/docs'
+
+    @staticmethod
+    def get_conf_examples(name, layers, templates):
+        outs = BaseOutput.simple_conf_examples(name, 'Simple project presentation', 'Presentation')
+        outs[0]['options'] = {'description': '# Presentation for '+GS.pcb_basename+'\n'
+                              'This is an automatically generated presentation page',
+                              'boards': {'mode': 'local', 'comment': 'Resources included',
+                                         'front_image': 'renderer_for_present',
+                                         'back_image': 'renderer_for_present',
+                                         'gerbers': 'gerbers_for_present'}}
+        # Renderer
+        renderer = BaseOutput.simple_conf_examples('pcbdraw', 'Renderer for the presentation', 'Presentation/Render')
+        renderer[0]['name'] = 'renderer_for_present'
+        outs.append(renderer[0])
+        # Gerbers
+        gerber = BaseOutput.simple_conf_examples('gerber', 'Gerbers for the presentation', 'Presentation/Gerber')
+        gerber[0]['name'] = 'gerbers_for_present'
+        gerber[0]['layers'] = 'copper'
+        outs.append(gerber[0])
+        return outs

tests/yaml_samples/kikit_present_auto_2.kibot.yaml

@@ -0,0 +1,40 @@
+kiplot:
+  version: 1
+
+outputs:
+  - name: KiKit_present_files
+    comment: "Present test using full auto mode"
+    type: kikit_present
+    dir: Present/Auto
+    options:
+      description: |
+        # My project
+
+        This is my project
+      boards:
+        mode: local
+        comment: This is a comment
+      repository: 'https://github.com/INTI-CMNB/KiBot/'
+
+  - name: PcbDraw
+    comment: "PcbDraw test top"
+    type: pcbdraw
+    dir: PcbDraw
+    options:
+      format: svg
+      vcuts: true
+      warnings: visible
+      dpi: 600
+
+  - name: 'gerbers'
+    comment: "Gerbers for the Gerber god"
+    type: gerber
+    dir: gerberdir
+    layers: copper
+
+  - name: result
+    comment: Compress the gerbers
+    type: compress
+    options:
+      files:
+        - from_output: gerbers