Summary
Currently the docs site uses the default README. I suggest we have a custom README just for the docs to help devs better understand how to use the site. I will split this up into 3 sub issues:
- The Main section
- The Docs section
- The Project section
Details
Main Section (Applies to both Docs and Project)
- Create a custom README.md specifically for the /docs site (/docs/README.md)
- Do not reuse the main repo's README.md
- Add an overview of the docs site purpose (developer usage, internal notes, etc)
- Include tech stack
- Link back to github page
Docs Contribution Section
- Docs are generated using JSDoc
- Edit, add, or remove JSDoc comments in src/ (main source files)
- Run
npm run docs (installs dependencies automatically)
- Output is written to /docs
- JSDoc config is defined in jsdoc.json
- Use valid JSDoc comment blocks (see example below)
Project Development Section
- Main source code lives in /src
- Explain scripts (build & serve)
- Use VS Code (launch.json) variant scripts
- Explain how js comments work with JSDoc (see example of jsdoc comment below)
- Follow existing file structure and code style
- Submit PRs for both doc and code changes
Example
/**
* Calculates the area of a rectangle.
*
* @function calculateRectangleArea
* @param {number} width - The width of the rectangle in units.
* @param {number} height - The height of the rectangle in units.
* @returns {number} The calculated area (width × height).
* @throws {TypeError} If either `width` or `height` is not a number.
* @example
* // Basic usage
* const area = calculateRectangleArea(5, 10);
* console.log(area); // 50
*
* @see {@link https://en.wikipedia.org/wiki/Rectangle|Rectangle on Wikipedia}
*/
function calculateRectangleArea(width, height) {
if (typeof width !== 'number' || typeof height !== 'number') {
throw new TypeError('Width and height must be numbers.');
}
return width * height;
}
Summary
Currently the docs site uses the default README. I suggest we have a custom README just for the docs to help devs better understand how to use the site. I will split this up into 3 sub issues:
Details
Main Section (Applies to both Docs and Project)
Docs Contribution Section
npm run docs(installs dependencies automatically)Project Development Section
Example