CONTRIBUTING.md

Contributing to the RAKwireless doc site

Contributing to the RAKwireless documentation site requires basic knowledge of GitHub and general Git workflow. Also, there is a need to set up a working development environment.

1. Setup local clone of private repository

Prerequisites:

• Install code editor (preferably VS Code )
• Install Node JS
• Install Yarn package manager

1. Open terminal / command prompt
2. Change directory to your desired location (where you want to put rakwireless-docs repository)
3. Clone the repository: git clone [email protected]:RAKWireless/rakwireless-docs.git
4. Change directory: cd rakwireless-docs
5. Initialize modules: yarn install
6. Run the local dev server: yarn docs:dev

2. Making content changes and pull requests

1. Change directory to where rakwireless-docs folder is located
2. From the root of the folder, make sure that the current branch is master: git branch

   

3. Make sure the master branch is updated: git pull origin master

   

4. Branch out from master to commit some changes: git checkout -b <branch_name>

   

5. Make some changes and commit

   

6. Push your changes to remote repository: git push origin <branch_name>

   

7. In GitHub, create a pull request and wait for your PR to be accepted and merged into the master

   

   📝 NOTE:
   Create a detailed description of your pull request. Your PR's description must match exactly what the PR contains. Consider your PR automatically rejected if its description is not that detailed and informative.

3. Important things to remember when editing *.md files

1. Basic file structure of the repository
   

   Most of the contents, lie on docs, like Introduction, Knowledge-Hub, Product-Categories, and RUI. Be sure to use the same naming convention for folders and markdown files.

   

2. All the images about devices are located and categorized in docs > .vuepress > public > assets > images. Make sure you put the images for the content here correctly.

   

3. For cited images to be zoomable and adjustable, we don’t use the markdown style of inserting images (![Image](link)) but we use our custom component for that.
   The component has four (4) properties:

   • src - the url/location of the image
   • figure-number - optional (figure numbers for all images in a page are auto-generated) custom figure number
   • width - custom width
   • caption - figure caption

   
   Refer to the example below.

   

   <<<<<<< HEAD The component has four (4) properties: src - the url/location of the image figure-number - optional (figure numbers for all images in a page are auto-generated) custom figure number width - custom width caption - figure caption

   =======

   a9887741d ([#984.1] - Minor updates on CONTRIBUTING.md)

4. All the overview pages of devices (e.g. docs/Product-Categories/WisLink/RAK2245-Pi-HAT/Overview/README.md) have 3 basic frontmatter properties:

   • rak_img - url/location of device image
   • rak_desc - short description of the device, shown when the mouse is hovered over the card
   • rak_grp - group of the device, string if it belongs to one group, array if it belongs to a group and subgroup