2023-02-03 16:13:18 +08:00
|
|
|
|
# sinara-assembly
|
|
|
|
|
|
2023-02-03 16:55:09 +08:00
|
|
|
|
Repository with instructions and remarks on assembling and testing Sinara hardware
|
|
|
|
|
|
2024-06-18 15:31:09 +08:00
|
|
|
|
## Build docs
|
2023-02-03 16:55:09 +08:00
|
|
|
|
|
|
|
|
|
```shell
|
|
|
|
|
nix build
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The output files are in `result/book` directory.
|
|
|
|
|
|
2023-02-06 15:38:48 +08:00
|
|
|
|
### Development shell
|
2023-02-03 16:55:09 +08:00
|
|
|
|
|
|
|
|
|
```shell
|
|
|
|
|
nix develop
|
|
|
|
|
mdbook build
|
|
|
|
|
```
|
|
|
|
|
|
2024-06-18 15:31:09 +08:00
|
|
|
|
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.
|
2023-02-06 15:38:48 +08:00
|
|
|
|
|
2023-02-06 15:56:22 +08:00
|
|
|
|
## 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`
|
2023-02-07 11:55:15 +08:00
|
|
|
|
2. Add pictures if needed, store them in `src/img`, assure them to be clear, informative and compressed
|
2023-02-13 14:15:36 +08:00
|
|
|
|
(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)
|
2023-02-06 15:56:22 +08:00
|
|
|
|
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
|
2024-05-16 13:04:05 +08:00
|
|
|
|
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)
|