Prepare deployment

.github/FUNDING.yml

@@ -0,0 +1,12 @@
+# These are supported funding model platforms
+
+github: yaqwsx
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: yaqwsx
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/workflows/build.yml

@@ -0,0 +1,54 @@
+name: Build
+on:
+  push:
+jobs:
+  build:
+    name: "Build pinion documentation"
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - name: Install dependencies and Pinion
+        run: |
+          set -e
+          sudo apt -qq update
+          sudo apt -qq install --yes --no-install-recommends \
+            zip inkscape make git libmagickwand-dev \
+            libgraphicsmagick1-dev libmagickcore-dev \
+            kicad npm
+          sudo npm install -g npm@latest
+
+          sudo python -m pip install mkdocs svgpathtools
+          sudo python -m pip install -e .
+          cd pinion-widget
+          npm install
+          sudo npm install -g craco
+
+          cd ..
+          sudo chown -R $USER .
+      -  name: Build pinion package
+         run: |
+          set -e
+          make package
+      - name: Upload pinion package artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: pinion-package
+          path: dist
+          retention-days: 14
+      - name: Upload pinion-widget package artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: pinion-widget-package
+          path: build/widget
+          retention-days: 14
+      - run: |
+          make web
+      - name: Deploy to GH Pages
+        if: github.ref == 'refs/heads/main'
+        uses: JamesIves/[email protected]
+        with:
+          branch: gh-pages
+          folder: site
+          single-commit: true

.gitignore

@@ -127,3 +127,9 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+
+site/
+
+doc/releases
+doc/resources/alksDemo

MANIFEST.in

@@ -1,2 +1,4 @@
 include versioneer.py
 include pinion/_version.py
+recursive-include pinion/resources *
+exclude pinion/resources/.gitignore

Makefile

@@ -0,0 +1,21 @@
+.PHONY: web clean package release widgets
+
+all: web package
+
+web:
+	releng/buildAlksDiagram.sh
+	releng/buildWidgetReleases.sh
+	mkdocs build
+
+package:
+	releng/syncWidgetVersion.sh
+	releng/updatePinionWidgetResources.sh
+
+	rm -f dist/*
+	python setup.py sdist bdist_wheel
+
+release: package
+	twine upload dist/*
+
+clean:
+	rm -rf dist build site

README.md

@@ -1,2 +1,45 @@
-# Pinion
-Generate interactive and sexy-looking diagrams for your PCBs!
+# Pinion — Nice-looking interactive diagrams for KiCAD PCBs
+
+Pinion is a simple tool that allows you to make a nice-looking pinout diagrams
+for your PCBs like this:
+
+![Screenshot](docs/resources/screenshot.png)
+
+[Live demo](https://yaqwsx.github.io/Pinion/alksStandalone.html)
+
+The diagrams are static HTML & Javascript files that you can easily include in
+your documentation. You do not need any backend, so you can easily serve them on
+your web page or Github pages. It is really simple!
+
+## Documentation
+
+The documentation is available at
+[https://yaqwsx.github.io/Pinion](https://yaqwsx.github.io/Pinion).
+
+## Do you enjoy Pinion or does it save your time?
+
+Then definitely consider [**supporting me on GitHub
+Sponsors**](https://github.com/sponsors/yaqwsx) or buy me a coffee:
+
+[![ko-fi](https://www.ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/E1E2181LU)
+
+You support will allow me to allocate time to properly maintain my projects like
+this.
+
+PS: Be sure to check out my other KiCAD & PCB related projects:
+
+- [KiKit](https://github.com/yaqwsx/KiKit/)
+- [PcbDraw](https://github.com/yaqwsx/PcbDraw/)
+- [JlcParts](https://github.com/yaqwsx/jlcparts)
+
+## Pinion is broken. What can I do about it?
+
+If something is not working as expected, please open an [issue on
+GitHub](https://github.com/yaqwsx/Pinion/issues). Please, provide as many
+resources as possible and clear instructions on reproduction of the bug.
+
+If you have a proposal for a new feature or you are just unsure about Pinion
+usage, you can start a [discussion on
+GitHub](https://github.com/yaqwsx/Pinion/discussions).
+
+

docs/alksStandalone.html

@@ -0,0 +1,16 @@
+<html>
+    <head>
+        <title>Pinion standalone demo</title>
+    </head>
+
+    <body>
+        <div style="width: 100%;" id="pinionDemo"></div>
+        <script src="releases/latest/pinion.js"></script>
+        <link rel="stylesheet" href="releases/latest/pinion.css">
+        <script>
+            pinion.setup(document.getElementById("pinionDemo"), {
+                source: "resources/alksDemo"
+            });
+        </script>
+    </body>
+</html>

docs/diagramWalkthrough.md

@@ -0,0 +1,131 @@
+# Making a diagram
+
+To make a diagram you have to:
+
+- specify which pins and components should be highlightable. This is done via
+  specifying a simple YAML file.
+- Build the diagram. This will generate a directory with several files.
+- Embed it in your webpage/documentation.
+
+## Basic concepts
+
+Pinion consists of two parts - diagram generator `pinion` (that you run on your
+computer) and a Javascript library that you include on your webpage, which
+reads and displays the diagram (`pinion-widget`).
+
+Pinion can highlight components and pins of components. Each of these objects
+can have assigned a verbose description. This description is shown on mouse
+hover/click. Each object can belong to any number of groups. The user has the
+ability to highlight a given group.
+
+## Defining a diagram
+
+The diagram is specified via YAML file with the following structure:
+
+```yaml
+name: <name of the diagram>
+description: <diagram description>
+components: # A dictionary of component reference to component description
+    <componentRef>:
+        description: <component description>
+        groups: <a list of groups>
+        highlight: true/false
+        pins: # A dictionary of pin names to pin description
+            <pinName>:
+                name: <human readable name of the pin>
+                description: <pin description>
+                alias: <pinName> # Use description of other pin. Alternative for description
+                groups: <a list of groups>
+groups: # An optional dictionary specifying tree structure of the groups, e.g.:
+    Peripherals:
+        - Adc
+        - SPI
+        - I2C
+    Pins:
+        - Digital
+        - Analog
+```
+
+Note that you can use markdown in descriptions to make them pretty. You should
+specify only the pins and components you want to be highlightable.
+
+It you remember the [example diagram](alksStandalone.html), it was generated by
+the [this YAML file](resources/alksSpec.yml).
+
+To save you some typing, Pinion can generate a template for your. Simply invoke:
+
+```
+pinion template \
+    --board <path to .kicad_pcb file> \
+    --output <path to YAML file> \
+    --components <comma separated list of component references>
+```
+
+Then you can modify the template as you need.
+
+## Building the diagram
+
+To build the diagram, simply invoke:
+
+```
+pinion generate \
+    --board <path to .kicad_pcb file> \
+    --specification <your YAML file> \
+    <path to output directory>
+```
+
+This will generate all files required. Note that the board image is generated
+via [PcbDraw](https://github.com/yaqwsx/PcbDraw). Therefore, if you struggle to
+generate the board image correctly, try using PcbDraw directly first to locate
+the issue.
+
+That also means that you can pass PcbDraw options to `pinion generate` to e.g.,
+remap your components, specify color scheme or point PcbDraw to the right
+libraries. You read more about the details at [PcbDraw
+documentation](https://github.com/yaqwsx/PcbDraw/blob/master/doc/pcbdraw.md).
+
+The supported options are:
+    - `--dpi` to specify image DPI
+    - `--style` to specify style (i.e., color scheme)
+    - `--libs` to specify the footprint library
+    - `--remap` to remap component footprints
+    - `--filter` to hide some footprint on the board.
+
+The directory is the diagram specification that can be . Note that you can also
+specify the option `--pack` that will include `pinion-widget` and a simple,
+stand-alone page with the diagram. You should upload the entire directory on
+your web page.
+
+## Including the pinion widget on your webpage
+
+Including pinion on a web page is simple. Just include the `pinion-widget`
+script, stylesheets and set it up:
+
+```html
+<div id="pinionDemo"></div>
+
+<script src="resources/pinion.js"></script>
+<link rel="stylesheet" href="resources/pinion.css">
+
+<script>
+    pinion.setup(document.getElementById("pinionDemo"), {
+        source: "resources/alksDemo"
+    });
+</script>
+```
+
+The first block creates a container in which we will the widget will be
+included. It can be anywhere on the page. Note that we will later need to
+reference this container, so we specify an id for it.
+
+The second block loads pinion code and styles. You can either host these files
+by yourself or use CDN (will be specified later). The precise location depends
+on your setup.
+
+In the third block, we start the widget. The first argument of `pinion.setup` is
+the container for the widget and the second argument is a dictionary that
+configures the widget. Currently, the only option is `source` that has to
+contain a location to the source directory (note that it can also be an absolute
+path).
+
+And this is it. When you load your page, the diagram should be running!

docs/faq.md

@@ -0,0 +1,22 @@
+# Frequently asked questions
+
+## Pinion says `pcbnew: no module found`
+
+This message probably means that you either:
+
+- you are running Windows or Mac. In that case until KiCAD 6 is released, you
+  have to use one of the alternative methods of usage - see
+  [installation](installation.md).
+- you are running Linux, but you don't have KiCAD installed
+
+## The diagram does not show up!
+
+If the diagram does not show up, there can be several reasons:
+
+- you have either script or source location wrong. Open developer tools in your
+  browser and inspect logs what went wrong.
+- you open a page from local file system (the URL in browser starts with
+  `file://`). In that case `pinion-widget` is not able to load the specification
+  as modern browsers prevent from loading local files (due to security reasons).
+  Try running `python3 -m http.server 8000` in the directory and then open
+  `http://localhost:8000` in your browser.

docs/index.md

@@ -0,0 +1,50 @@
+# Pinion — Nice-looking interactive diagrams for KiCAD PCBs
+
+Pinion is a simple tool that allows you to make a nice-looking pinout diagrams
+for your PCBs like this (see also [a standalone version](alksStandalone.html)).
+For the sake of clarity what is documentation and what is the diagram, we put it
+inside a frame — in production, you can seamlessly include it in your page.
+
+<div style="width: 100%; border: solid 2px #2563EB; border-radius: 10px;" id="pinionDemo"></div>
+<script src="releases/latest/pinion.js"></script>
+<link rel="stylesheet" href="releases/latest/pinion.css">
+<script>
+    pinion.setup(document.getElementById("pinionDemo"), {
+        source: "resources/alksDemo"
+    });
+</script>
+
+The diagrams are static HTML & Javascript files that you can easily include in
+your documentation. You do not need any backend, so you can easily serve them on
+your web page or Github pages. It is really simple!
+
+## Making your first diagram
+
+...is easy. Just [install Pinion](installation.md) and then follow the
+[walkthrough](diagramWalkthrough.md).
+
+## Pinion is broken. What can I do about it?
+
+If something is not working as expected, please open an [issue on
+GitHub](https://github.com/yaqwsx/Pinion/issues). Please, provide as many
+resources as possible and clear instructions on reproduction of the bug.
+
+If you have a proposal for a new feature or you are just unsure about Pinion
+usage, you can start a [discussion on
+GitHub](https://github.com/yaqwsx/Pinion/discussions).
+
+## Do you enjoy Pinion or does it save your time?
+
+Then definitely consider [**supporting me on GitHub
+Sponsors**](https://github.com/sponsors/yaqwsx) or buy me a coffee:
+
+[![ko-fi](https://www.ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/E1E2181LU)
+
+You support will allow me to allocate time to properly maintain my projects like
+this.
+
+PS: Be sure to check out my other KiCAD & PCB related projects:
+
+- [KiKit](https://github.com/yaqwsx/KiKit/)
+- [PcbDraw](https://github.com/yaqwsx/PcbDraw/)
+- [JlcParts](https://github.com/yaqwsx/jlcparts)