Improving documentation + adding templates

README.md

@@ -1,11 +1,98 @@
-# Raspberry Pi PCI Express device compatibility database
+# Raspberry Pi PCIe Devices
 
-This repository builds the GitHub pages site: [http://pipci.jeffgeerling.com](http://pipci.jeffgeerling.com)
+<!--- shields were customized from https://shields.io/ --->
+![GitHub repo size](https://img.shields.io/github/repo-size/geerlingguy/raspberry-pi-pcie-devices)
+![GitHub last commit](https://img.shields.io/github/last-commit/geerlingguy/raspberry-pi-pcie-devices)
+![GitHub stars](https://img.shields.io/github/stars/geerlingguy/raspberry-pi-pcie-devices?style=social)
+[![Sponsors](https://img.shields.io/github/sponsors/geerlingguy)](https://github.com/sponsors/geerlingguy#sponsors)
+![license](https://img.shields.io/github/license/geerlingguy/raspberry-pi-pcie-devices?logoColor=blue)
 
-If you would like to add a new device to the site, or correct the information about an existing device, please file a Pull Request against this repository.
+[**Raspberry Pi PCIe Devices**](https://pipci.jeffgeerling.com/) is a compatibility database that tracks which devices are and are not compatible with the [Raspberry Pi CM4](https://www.raspberrypi.com/products/compute-module-4/).
 
-## Local Editing
+<p align="center">
+  <img src="/images/cm4-io-board-pcie-slot.jpeg" alt="CM4 IO Board PCIe Slot"/>
+</p>
 
-This site uses Jekyll to build and serve pages. On a local workstation, clone the repository, make sure you have Ruby, Bundler, and Jekyll installed, then run `jekyll serve`.
+# Setup and installation
 
-Access the local site at the address Jekyll provides.
+To run a copy of this website in a local web development environment, you need to have **Jekyll**, **GitHub CLI** *OR* **GitHub Desktop**, and a local clone of the website's repository.
+
+### Jekyll
+This site is built using [Jekyll](https://jekyllrb.com/), a [Ruby](https://www.ruby-lang.org/en/) gem.
+
+**To install Jekyll:**
+1. Visit Jekyll's [installation page](https://jekyllrb.com/docs/installation/) in your browser
+2. Click the guide for your operating system (macOS, Ubuntu, Other Linux, or Windows)
+3. Follow the step-by-step instructions to install Jekyll.
+
+### GitHub
+There are two ways to use GitHub locally:
+* via [GitHub CLI](https://cli.github.com/), using the command line
+* via [GitHub Desktop](https://desktop.github.com/), an app available for macOS and Windows
+
+# Contributing
+
+## Ways to contribute:
+* **Add a card or board to the list:** Use issues and pull requests to add new board entries and card entries to the site.
+* **Test a card yourself:** If you want to test a card on your own, I'm happy to add it to the database, provided you give all the testing details, information like `lspci` and `dmesg` logs, etc. in a GitHub issue, and follow the project's conventions for card details.
+* **Fix problems with the repository:** If you find any typos, incorrect links or images, or other issues in this repository, please submit a pull request to fix the problem or [open a new issue](https://github.com/geerlingguy/raspberry-pi-pcie-devices/issues/new/choose) to point the problem out for someone else to fix.
+* **Mail me a card or board:** I accept cards and boards mailed to me, and can occasionally pay shipping as well. I credit senders in all videos/posts that result from donated card testing!
+
+## General instructions for contributing
+To contribute to **Raspberry Pi PCIe Devices**, follow these steps:
+1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) this repository.
+2. [Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) that new repository to your device.
+3. Create a [new branch](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/managing-branches#creating-a-branch).
+3. (Optional) use `jekyll serve` to build the site in your local development environment while you're working on it.
+4. Once you're satisfied with your changes, [commit them](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project).
+5. [Push](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/pushing-changes-to-github) the changes to the correct branch.
+6. Create a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
+7. Give yourself a high five, you did a great job. Thanks for contributing!
+
+## Add a card
+Add a new file named after the card in the appropriate `_cards_[type]` directory.
+Copy the template out of [`card-template.md`](card-template.md) into this new file and follow the instructions it contains.
+
+### Specific example: Adding a network card
+To add a network card to the database:
+1. Make sure a GitHub [issue](https://github.com/geerlingguy/raspberry-pi-pcie-devices/issues) exists for the card. Open a new issue for it you find that there isn't one.
+2. Copy the template into a new Markdown file you create inside `_cards_network`.
+3. Fill in the card information as described in [`card-template.md`](card-template.md).
+4. Place a picture of the card named network-[name-of-card-here-minus-brackets].jpg inside the `images/` folder.
+5. Submit a pull request with your changes.
+
+## Add a board
+Add a new file named after the card in the appropriate `_boards_cm` directory.
+Copy the template out of [`board-template.md`](board-template.md) into this new file and follow the instructions it contains.
+
+# Development
+
+Once you have Jekyll running and the [raspberry-pi-pcie-devices repository](https://github.com/geerlingguy/raspberry-pi-pcie-devices) cloned, you can build and run the site locally.
+
+### Build the site locally
+1. In the command line, `cd` into the `raspberry-pi-pcie-devices` folder that contains the cloned repository.
+2. To build the site, run `jekyll serve`.
+3. You should now be able to access the local site at http://localhost:4000 in your web browser of choice.
+
+As long as `jekyll serve` is running, you'll be able to watch the site and all changes you make to it in real time.
+
+# Support
+Drop a ⭐ if this project helped you!
+
+![Patreon](https://img.shields.io/badge/-Patreon-f96854?style=for-the-badge&logo=patreon&logoColor=white)
+
+# Authors
+### Jeff Geerling
+* Creator and maintainer
+* [@geerlingguy](https://github.com/geerlingguy) on GitHub
+* [![YouTube](https://img.shields.io/youtube/channel/subscribers/UCR-DXc1voovS8nhAvccRZhg?style=social)](https://www.youtube.com/c/JeffGeerling)
+
+### Katie Geerling
+* Documentation writer and part-time contributor
+* [@punnypenguins](https://github.com/punnypenguins) on GitHub
+
+# License
+
+This project is maintained by [Jeff Geerling](https://www.jeffgeerling.com/). The Raspberry Pi Compute Module 4 is a product of [Raspberry Pi (Trading) Limited](https://www.raspberrypi.org/about/).
+
+_**Raspberry Pi PCIe Devices** uses the [GNU General Public License, version 3](https://opensource.org/licenses/GPL-3.0)._

board-template.md

@@ -0,0 +1,44 @@
+---
+layout: board
+title: "Name of Board Here"
+short_description: Insert a single sentence summary of the board here.
+status: Here
+picture: "/images/board-(and-then-insert-name-here-without-parentheses).jpg"
+github_issue: "https://github.com/geerlingguy/raspberry-pi-pcie-devices/issues/ID-here"
+link: https://amzn.to/product-link-here
+videos: []
+---
+# INSTRUCTIONS:
+
+### Create a new file in the `_boards_cm` directory.
+
+1. Title it with the board name in all-lowercase, using dashes to separate words.
+2. Save it as Markdown file (.md extension).
+3. Paste the contents of this template into the new file.
+4. Replace all the values in its top section with the proper information:
+  - `layout`: Should be left alone! Don't change this.
+  - `title`: Replace *Name of Board Here* with the full name of the board.
+  - `short_description`:
+  - `status`: Can be one of these:
+    * prototype
+    * production
+    - `picture`: Can have a path to a picture like `/images/[card type]-card-name.jpg`, or `false`.
+      - `card type` can be
+        - adapter
+        - gpu
+        - m2
+        - multimedia
+        - network
+        - other
+        - storage
+        - usb
+      - `file type` can be
+        - png
+        - jpg
+        - jpeg
+      Make sure you remember to drop the image into the `images` folder before you submit your pull request!
+  - `github_issue`: Should link to the GitHub issue corresponding to this card.
+  - `link`: should link to the Amazon product page for this card. If no Amazon listing is available, you can substitute a different website instead.
+  - `videos`: Is a list of YouTube video URLs. If there is a video to add, delete the `[]`, hit return, tab in once, add a dash, press the spacebar, and then paste the video url.
+
+Finally, replace all content below the second `---` line with a description of the board, save your changes, and submit the finished entry via pull request.

card-template.md

@@ -1,20 +1,49 @@
 ---
 layout: card
 title: "Name of Card Here"
-picture: "/images/name-of-image-here.jpg"
-functionality: "Currently Testing"
-driver_required: "Yes"
+picture: "/images/[card type]-(and-then-insert-name-here-without-parentheses).jpg"
+functionality: "Functionality goes here"
+driver_required: "Answer goes here"
 github_issue: "https://github.com/geerlingguy/raspberry-pi-pcie-devices/issues/ID-here"
 buy_link: https://amzn.to/product-link-here
 videos: []
 ---
-Copy this template into the appropriate `_cards_[type]` directory, and replace all the values above with the proper information:
+# INSTRUCTIONS:
 
-  - `picture`: can have a path to a picture like `/images/[type]-card.jpg`, or `false`
-  - `functionality`: can be one of "Currently Testing", "Full", "Partial", or "None"
-  - `driver_required`: can be one of "Yes", "Maybe", or "No"
-  - `github_issue`: should link to the GitHub issue corresponding to this card.
-  - `buy_link`: should link to the Amazon product page for this card.
-  - `videos`: is a list of YouTube video URLs.
+### Create a new file in the appropriate `_cards_[type]` directory.
 
-Then replace the text in this area with a description of the card.
+1. Title it with the card name in all-lowercase, using dashes to separate words.
+2. Save it as Markdown file (.md extension).
+3. Paste the contents of this template into the new file.
+4. Replace all the values in its top section with the proper information:
+  - `layout`: Should be left alone! Don't change this.
+  - `title`: Replace *Name of Card Here* with the full name of the board.
+  - `picture`: Can have a path to a picture like `/images/[card type]-card-name.jpg`, or `false`.
+    - `card type` can be
+      - adapter
+      - gpu
+      - m2
+      - multimedia
+      - network
+      - other
+      - storage
+      - usb
+    - `file type` can be
+      - png
+      - jpg
+      - jpeg
+    Make sure you remember to drop the image into the `images` folder before you submit your pull request!
+  - `functionality`: Can be one of the following:
+    * "Currently Testing"
+    * "Full"
+    * "Partial"
+    * "None"
+  - `driver_required`: Can be one of the following:
+    * "Yes"
+    * "Maybe"
+    * "No"
+  - `github_issue`: Should link to the GitHub issue corresponding to this card.
+  - `buy_link`: Should link to the Amazon product page for this card. If no Amazon listing is available, you can substitute a different website instead.
+  - `videos`: Is a list of YouTube video URLs. If there is a video to add, delete the `[]`, hit return, tab in once, add a dash, press the spacebar, and then paste the video url.
+
+Finally, replace all content below the second `---` line with a description of the card, save your changes, and submit the finished entry via pull request.