How to use present command

[Yoliq]

Hi,

I have problems using present feature of kikit.

I find documentation and docs to be lacking additional info for me to understand properly.

I read through following files:
https://yaqwsx.github.io/KiKit/v1.4/cli/#modify-commands
https://yaqwsx.github.io/KiKit/v1.4/present/
https://roboticsbrno.github.io/RB0002-BatteryPack/

• carefully read output of kikit present boardpage --help command

My questions:

1. is somewhere described how to acquire --descriptor FILE ? I have no idea how that is supposed to look like and I did not found any examples of it. It should be *md file but I did not find any example of it. I tried putting there random markdown file test1.md which I created but I got following error:

C:\Users\danie\Documents\KiCad\.Projects\001 Robotwin - 22 mm RGB button shield\22mm_RGB_button_shield>kikit present boardpage --name "Page name" -d test1.md presentation/test
An error occurred: [WinError 2] The system cannot find the file specified

C:\Users\danie\Documents\KiCad\.Projects\001 Robotwin - 22 mm RGB button shield\22mm_RGB_button_shield>kikit present boardpage --name "Page name" -d test2.md presentation/test
An error occurred: [Errno 2] No such file or directory: 'test2.md'

Notice that for next command I tried test2.md file which was not present in the directory. The error was different.

2. what is format of --board option? Or even better, is it possible to provide example project with example command to create the presentation webpage? I am interested in this feature but I am stuck.

[gwideman]

I have not used this feature but...

2. what is format of --board option?
   Did you find the code that produces the BatteryPack example output? It's here:
   https://cadlab.io/project/22740/master/files/Makefile
   ... and shows the format of the -b (board) argument

1....
Your sample command line output suggests that kikit present found test1.md (because actual absent file test2.md produced different error message). Is there any possibility that test1.md happens to contain some syntax which attempts to include another file? You say that test1.md is some random file -- if it's actually a markdown file you got from somewhere else, it might have such a line in it.

As a general note on figuring out "missing file" errors, one extremely handy tool on Windows is SysInternals Process Monitor.
https://learn.microsoft.com/en-us/sysinternals/downloads/procmon

This will quickly show you what your program-of-interest is looking for.

[Yoliq]

I believe the system finds a .md file but the file needs to be in some specific format. And it seems the docs are not complete. I could try to deep dive into the code and find the solution there but I am trying first the most easy solution - find out if someone uses this feature and is familiar with it.

[gwideman]

You are aware that a .md file is a markdown file, right? For example, here's the present command from the BatteryPack example:

	kikit present boardpage \
		-d README.md \
		--name "Battery Pack" \
		-b "Charger Board" " " build/charger.kicad_pcb  \
		-b "Battery Board" " " build/battery.kicad_pcb  \
		-b "Connector Board" " " build/connector.kicad_pcb  \
		-b "Charger Board Panelized" " " build/charger-panel.kicad_pcb  \
		-b "Battery Board Panelized" " " build/battery-panel.kicad_pcb  \
		-b "Connector Board Panelized" " " build/connector-panel.kicad_pcb  \
		--repository 'https://github.com/RoboticsBrno/RB0002-BatteryPack' \
		build/web

Here the file referenced by the -d argument is README.md. You can download a README.md file from right here on Github, like the one for the BatteryPack project at https://cadlab.io/project/22740/master/files/README.md/nojs

I took a look and it does not have a command to include another file, so should be OK. There's no obvious special features in that file that the present function might be looking for, so far as I can see.

[Yoliq]

Wow I didnt know about this github page. I downloaded it and played around with it.

It looks like I am not able to pull this on Windows machine with my skills. To unwrap file make command needs to be called. Managed to have make command running via MSYS2, but unfortunately it needs access to kikit commands. Which is blocked on Windows machine, because you have access to kikit only via Kicad command prompt.

I tried to recreate commands via windows CMD / Kicad command prompt but to no luck.

[yaqwsx]

There are no special requirements for the description file; it is just a plain Markdown file with whatever content you want to have on your page. The message you see is rather strange; it means that the file was not found. Is the file really in the directory 22mm_RGB_button_shield? If you run KiKit via Docker image on Windows, there are sometimes problems with misconfigured Docker that prevents the access of the file (google on this topic).

Regarding usage; this is the help:

Usage: kikit present boardpage [OPTIONS] OUTDIR

  Build a board presentation page based on markdown description and include
  download links for board sources and gerbers.

Options:
  -d, --description FILE          markdown file with page text  [required]
  -b, --board <TEXT TEXT FILE>...
                                  <name> <comment> <kicad_pcb file> to include
                                  in generated page.
  -r, --resource PATH             Additional resource files to (e.g., images
                                  referenced in description) to include.
  --template PATH                 Path to a template directory or a name of
                                  built-in one. See doc/present.md for
                                  template specification.
  --repository TEXT               URL of the repository
  --name TEXT                     Name of the board (used e.g., for title)
                                  [required]
  --help                          Show this message and exit.

• What you need to do is to supply the page text (via --description). If there are images or other resources your markdown file mentions, you can specify a directory with them via --resource path-to-the-directory
• You also have to provide title of the page via --name "Page title"
• If you want to add board section to the page, you use --board "NameOfYourBoard" "Some textual description of the board" "path-to-the-boad". You can use this option multiple times.
• If you provide --repository URL to repository` it will be rendered and linked.
• lastly, you can use custom templates (which are rather poorly documented at the moment) via --template path-to-template.