Skip to main content

Getting started

This page contains instructions for developers who want to contribute to the Amiga Development Kit documentation.

We build our website with Docusaurus 2 with Markdown syntax. To get started:

  1. Clone the Amiga Development Kit repo
git clone git@github.com:farm-ng/amiga-dev-kit.git
cd amiga-dev-kit
git submodule update --init
  1. Create a branch based on main and open a pull request with your proposed improvements.
git checkout main
git pull
git checkout -b <your-new-branch>
# make your changes; then
git push -u origin <your-new-branch>
  1. Follow the instructions below for building the docs locally so you can see your changes in real time!
tip

If you aren't familiar with Markdown syntax, check out one of the many getting started guides available free online. Such as Markdown Guide.

Building these Docs

In order to work locally on your machine and contribute to these docs, you will need to install the build infrastructure.

caution

You can edit the documentation directly on github and do not need to fuss with things here! Follow instructions below for adding images to the website, it's the same for text.

Installation​

Docusaurus allows you to build the docs locally and inspect how the website will appear, before actually deploying.

In order to use docusaurus locally you'll need to install a couple libraries:

  • Node.js version 16.14 or above (which can be checked by running node -v)
  • Yarn >= 1.22.19

We recommend doing so in a virtual environment to avoid conflicts with other packages / versions installed on your system. Though this is not a requirement and you are welcome to decide how / where to install.

Install pip3 & virtualenv (system level):

sudo apt-get install python3-pip
sudo pip3 install virtualenv

Start a virtual environment:

# assuming you're already in the amiga-dev-kit/ directory
# or wherever you want your `venv` to exist
python3 -m venv venv
source venv/bin/activate

Install NVM / nodejs

sudo apt update
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
# source ~/.bashrc # if not using a venv

# Verify install
nvm --version

# Install node
nvm install node

Install yarn

sudo apt install npm
sudo npm install -g yarn

# Check version
yarn --version

Local Development​

After successful installation and working in the amiga-dev-kit github repo, you'll be able to pull down the latest, create a branch, and send pull requests just as you would editing any repo.

After making your edits, you will build the docs locally in order to preview them before committing and pushing. Following the steps below, you would be able to start a local development server that opens a browser window and gives you a live preview of the page you are editing! It will automatically update every time you save.

Building the docs​

cd website/  # /farm-ng/amiga-dev-kit/website
pip install -r requirements.txt
yarn
./run_pydoc-markdown.sh
yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

Start yarn​

info

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

yarn start

Later, you can exit your virtualenv with:

deactivate

Re-enter​

When you come back you can re-enter from the root where the venv was created (e.g., amiga-dev-kit/) with:

# assuming you're already in the amiga-dev-kit/ directory
# or wherever your `venv` exists
source venv/bin/activate
caution

You may find issues with the node, npm, or yarn version. If so, re-install these packages in your venv with:

nvm install node
# sudo apt install npm
npm install -g yarn

Then rebuild the yarn server;

cd website
yarn
yarn start

Best practices / tips​

  • Add command line instructions where possible, rather than just posting link to an external website
    • Links can be broken without us knowing!
  • .mdx allows for cool extensions included in the file
    • Like the tab for different installation instructions(e.g. Mac, Linux, Windows)
    • Use .mdx plugins to write JSX within your Markdown files and render them as React components.
  • Run pre-commit checks before committing / pushing
    • pre-commit run --all-files
  • Test your links!
  • Use the following VS Code extensions:
    • Code Spell Checker
    • Trailing Spaces
    • Markdown All in One
  • Gussy up your Markdown
tip

You can make your work more legible using admonitions like this TIP box! More markdown features can be found in the docusaurus documentation here.

Pre-commit formatting workflow​

caution

You may need to install pre-commit, instructions can be found here

A typical workflow for committing your code changes may look like this:

git add -p # Add the changes I want
pre-commit run --all-files
git add -p # Add the formatting changes the check just fixed
pre-commit run --all-files # double check for any formatting issues not resolved automatically (e.g., spellcheck)
git commit -m "foo bar baz"
git push

Adding to the website​

Adding pages​

The pages are defined in a file called website/sidebars.js. Depending on what you are adding you can choose to add it into the docs section or examples/ wherever would be most appropriate. The pattern and structure in sidebars.js should be clear.

For example :

If you want to add another section in between Dashboard and Debug Cable it will be something like this:

"docs": {
  "Introduction": [
    "getting-started",
  ],
  "Dashboard": [
    "dashboard/dashboard",
    "dashboard/dashboard-fw",
    "dashboard/control-states",
  ],
  "Debug Cable": [
    "debug_cable/debug-cable",
  ],

You can change it to:

"docs": {
  "Introduction": [
    "getting-started",
  ],
  "Dashboard": [
    "dashboard/dashboard",
    "dashboard/dashboard-fw",
    "dashboard/control-states",
  ],
  "My New Section": [
    "my_new_section/my-new-page",
  ],
  "Debug Cable": [
    "debug_cable/debug-cable",
  ],

Add a new directory website/docs/my_new_section/. Then you can add a markdown (*.md) file in that directory called my-new-page.md. The top of my-new-page.md should be:

---
id: my-new-page
title: My New Page
---

# Header of my new page

## Subheader 1

Now with your locally build docs you should see a new tab called "My New Section" with a page called "My New Page". If you open that page you should see it has the header of "Header of my new page".

Adding images​

info

If you are already working in an active branch, this process works for branched versions of markdown files. If you are not, you will be prompted to create a new branch with your edits (to open a pull request) or commit the edits directly.

We want to keep this repository as lightweight as possible. For this reason, please do not add any images to the filesystem of this repository. If you'd like to add an image, you should edit the README online through Github by:

  1. Press the edit button in the top right corner of the markdown file
  2. Drag & drop an image into the markdown file you are editing.
  3. A link to the image should be automatically generated and formatted in the markdown file.

The generated link should look something like: https://user-images.githubusercontent.com/11846963/185976402-ff8c4c77-5a08-42b0-865f-d2840fc0b960.jpg

caution

If you are also editing the file locally, you should add the image to the branch you are actively editing. Recommend committing your changes before adding the image to avoid merge conflicts, and using git pull to pull in the changes to your local branch before continuing to edit.

farm-ng employees

Please back up the images you add to the website in the Website/Assets/ directory of our shared drive (linked from Media Bin).

&nbsp &nbsp &nbsp

Thank you for your help building this community!​

The documentation website is built using Docusaurus 2.​