forked from sinara-hw/assembly
61 lines
1.9 KiB
Markdown
61 lines
1.9 KiB
Markdown
# sinara-assembly
|
||
|
||
Repository with instructions and remarks on assembling and testing Sinara hardware
|
||
|
||
## Build docs
|
||
|
||
```shell
|
||
nix build
|
||
```
|
||
|
||
The output files are in `result/book` directory.
|
||
|
||
### Development shell
|
||
|
||
```shell
|
||
nix develop
|
||
mdbook build
|
||
```
|
||
|
||
The output files will be in `book` directory.
|
||
|
||
### Alternative way
|
||
|
||
Since the docs builder depends only on mdBook, you may get it from anywhere you like - `nix-shell -p mdbook`,
|
||
`snap install mdbook`, `cargo install mdbook` or any other from your OS.
|
||
After that you will be able to do:
|
||
|
||
```shell
|
||
mdbook build
|
||
```
|
||
|
||
The output files will be in `book` directory.
|
||
|
||
## Contributing
|
||
|
||
If you found missing hardware or just want to add/enhance hints and instructions,
|
||
feel free to push them.
|
||
|
||
Tips for adding hardware instructions:
|
||
|
||
1. Compose a chapter in a new Markdown file in `src/hw`
|
||
2. Add pictures if needed, store them in `src/img`, assure them to be clear, informative and compressed
|
||
(you can use `convert <INPUT IMAGE> -quality 80% -resize <width>x<height> <OUTPUT IMAGE>` for optimizing JPEG image
|
||
or `convert <INPUT IMAGE> -quality 80% -resize <width>x<height> -background white -alpha remove -alpha off <OUTPUT IMAGE>`
|
||
for images with transparent background)
|
||
3. Add link to the new chapter to the `src/SUMMARY.md`
|
||
4. Do not forget to tell about all hidden/non-obvious obstacles and pitfalls
|
||
5. Avoid using uncommon, complex, or hard-to-understand words, phrases, or grammar (e.g., ❌constituent -> ✔️component).
|
||
Keep in mind that these guides may be used by people with different backgrounds and levels of English proficiency.
|
||
6. Add testing steps, even the "obvious" ones
|
||
7. Add JSON sample if needed
|
||
8. Add hardware setup (e.g. pins, switches) steps if needed
|
||
9. View changed and added pages with `mdbook build` (see building instructions above)
|
||
10. Check your contributions with linter:
|
||
|
||
```shell
|
||
nix-shell -p nodejs
|
||
npm install
|
||
npx markdownlint-cli2 "src/**/*.md" --fix
|
||
```
|