cpr-documentation-docusaurus

Links to the deployed website:

• production branch
• development branch

Tools used:

1. Node.js
2. Docusaurus by Facebook / Meta
3. GitHub
4. AWS Amplify

Steps to run this on your computer locally:

1. System dependencies, common to most web development
   1. VS code, or similar editor
      • Extension: Git Lens
      • Extension: Prettier
      • Extension: MDX
   2. Terminal configured to work with this GitHub repository
   3. Node.js is installed
2. Clone this repository
3. Open the folder
4. In a terminal, navigate to the root of the project folder and run npm install
5. Start the local server by running npm run start
6. A new tab should open in your prefered web browser once the site is running. Your terminal session should show the port the webpage is running on. The default address is http://localhost:3000/ but this may change if you are already using that port for another site.

Workflow for making updates:

1. Clone or fork this repository

2. Create a branch from development. with a name indicating the purpose, such as feature_xxxxxx

3. Make changes to the relevant files

4. Test using your local server, using the steps mentioned Steps to run this on your computer locally

5. When ready, enter ctrl-c in your terminal to stop the server. Then run npm run build to test that the site builds corretly.

6. Resolve any errors that the terminal reports, and rerun the command npm run build.

7. Finally, check that your updates adhere to our conde formatting standard, by running the command npm run format-check. The terminal will either report:

   • All matched files use Prettier code style!
   • Code style issues found in the above file(s). Forgot to run Prettier? You can fix the errors by running the command npm run format-write.

8. You will need to confirm that npm run format-write code formatting did not make any functionality changes to your .mdx documentation. You may see files that claim to be updated in Source Control, but don't have any visible changes. You should run these commands in your terminal to prevent Git from noting these types of changes:

       git config --global core.filemode false
       git config --global core.autocrlf false
   

9. When ready, publish your branch, and submit a Pull Request to merge your changes into the development branch. Pull Requests to the production branch will not merged.

10. The administrators of this documentation will review the website for any functional issues, and will periodically merge the latest commits in the development branch into the production branch.

How should I write pages?

1. Refer to Markdown's guide for syntax
2. Refer to Docusaurus's guide for supported Markdown features
3. For advanced users, refer to Markdown MDX for adding React Components to a Markdown file
4. for advanced users, you may create React pages using .js or .ts file types

Where should I place files?

1. Markdown page

   /docs
   

2. Markdown component, like a section to be reused in multiple pages

   /components
   

3. Images

   /static/img
   

How does the deployed website get updated?

We have this site deployed on AWS Amplify. Their server is monitoring the production and development branches of this repository. When AWS sees a new commit on either branch, it will rebuild the site. The image below shows the development branch rebuilding after the GitHub branch was updated by a Pull Request.

This example took 2 minutes and 14 seconds to deploy. If your feature branch change is large, we can deploy it as a temporary site on AWS to confirm that it builds before submitting a Pull Request into Development. The downsides of deploying more branches are:

• Possible time lost, though this may save time by preventing build errors on the production branch
• A small cost to AWS for using their Server. At the time of writing (May 2022), AWS charges $0.01 USD per build minutes

Structure for Sensor pages

1. Safety
2. Item numbers
3. Specifications, overview (view angles, mass, voltage, ingress protection)
4. specifications, IP addresses
5. Specifications, pinout
6. Hardware build, part numbers
7. Hardware nuild, instructions
8. Support, troubleshooting
9. Support, contact
10. Further reading, links

Equations

You can add equations using KaTex syntax. The packages have are installed in the package.json and imported into the project in docusaurus.config.js. You simply need to add your equations to your Markdown file, keeping all the elements between opening an closing tags $.

$$ \omega=\cfrac{v_{r}-v_{l}}{w} $$

You can test equation syntax using this tool from KaTex.