Skip to content

getting-started.md

Latest commit

 

History

History
126 lines (81 loc) · 4.98 KB

getting-started.md

File metadata and controls

126 lines (81 loc) · 4.98 KB
Raw

Getting Started

This guide takes you end to end: from a photo of your board to an interactive pinout you can drop into a documentation site. It should take about five minutes.

PinConnect has three tools, used in sequence:

  1. pinout-design: a browser-based designer that turns a board image into a TOML config.
  2. pinout-gen: a CLI that reads that TOML and generates a single interactive HTML pinout.
  3. pinout-embed: an optional Markdown extension that embeds the generated HTML into MkDocs / Zensical sites.

You only need the first two to get a working pinout. The third is for people publishing to a Markdown docs site.

Prerequisites

  • Python 3.9 or newer (python --version)
  • A top-down image of your board (PNG, JPG, or any other format your browser can display)
  • A copy of this repository

Step 1: Design your pinout

The designer is a static web app. It reads its connector, theme, and symbol data over fetch(), so it must be served over HTTP — opening index.html directly with file:// will not work.

Start a local server from the pinout_design folder:

PowerShell

cd pinout_design
python -m http.server 8000

Linux / macOS

cd pinout_design
python3 -m http.server 8000

Then open http://localhost:8000 in your browser.

In the designer:

  1. Click Open Image and select your board photo.
  2. Click + Add Connector, drag a box over a connector on the image, then fill in the New Connector dialog (an ID is suggested for you, and the name defaults to the ID) and click Create. Draw mode switches off after each one, so click the button again for the next connector.
  3. Select a connector to refine it in the editor panel: its type, name, description, and per-pin labels and colors.
  4. Optionally pick a Theme from the toolbar to change how the generated pinout will look.
  5. Watch the TOML Source pane update live as you work.
  6. Click Save TOML to save your board config (for example board.toml).

Put the saved .toml next to your board image — the next step expects them together.

See pinout-design for a full tour of the designer.

Step 2: Generate the HTML

Install the generator from the repository root. Using a virtual environment is recommended but optional.

PowerShell

python -m venv venv
./venv/Scripts/activate
pip install .\pinout_gen

Linux / macOS

python3 -m venv venv
source venv/bin/activate
pip install ./pinout_gen

This installs the pinout-gen command. Run it on your config:

pinout-gen board.toml

By default this writes board.pinout.html next to the config. Use -o to choose a different path:

pinout-gen board.toml -o docs/my-board.html

A theme sets the generated page's colors, fonts, and layout behavior. Five ship with the tool — default, midnight, ocean, slate, and terminal — and -t picks one for a single run, overriding whatever the board config says:

pinout-gen board.toml -t midnight

Keep the image alongside the output. By default the generated HTML links to your board image by the same relative path used in the TOML — it is not embedded. Make sure the image file sits next to the HTML (or serve both from the same folder) or the diagram will show a broken image. To embed the image into the file instead, add -i: pinout-gen board.toml -i. Note that -i covers the image only — the default theme still loads its font from Google Fonts, so see themes if you need output with no external references at all.

Open the resulting .html file in a browser to check your interactive pinout. You should get something like this:

A generated PinConnect pinout: hovering a connector on the board shows its pinout, and the connector list browses every connector at once

See generating HTML and board TOML reference for more, or Installation for editable installs and optional extras.

Step 3: Embed it in a docs site (optional)

If you publish with MkDocs or Zensical, pinout-embed lets you drop the generated pinout into a page with an image-style tag:

![Board Pinout](my-board.pinout.html){ type=application/pinout style="min-height:60vh;width:100%" }

The extension replaces that tag with a responsive <iframe> at build time.

See pinout-embed for installation and configuration.

Where to go next

  • Concepts: how the pieces fit together and the three kinds of TOML file — board, connector type, and theme.
  • pinout-design: designing configs visually.
  • pinout-gen: CLI usage, board TOML, and connector types.
  • themes: restyle the pinout's colors, fonts, and behaviors, or write your own theme.
  • pinout-embed: embedding in a Markdown site.