GitHub - Dasharo/docs: Scalable, modular, and easy to combine BIOS firmware technology without boundaries on processor architecture. (original) (raw)

About

This repository contains source code for the Dasharo documentation webpage

Contribution

Please make sure to follow below steps before publishing your changes as a merge request.

Local build

virtualenv -p $(which python3) venv source venv/bin/activate pip install -r requirements.txt mkdocs serve

By default, it will host a local copy of documentation at:http://0.0.0.0:8000/.

If the following error occurs OSError: [Errno 98] Address already in use, try using a different address by running the command mkdocs serve -a localhost:12345 (the number is random).

It is crucial at this point to verify that the pages you have changed render correctly as HTML in local preview.

It is also important to read through the console output after running mkdocs serve. You should definitely eliminate any WARNINGs related to your contribution before submitting it for review, and you should consider applying suggestions marked as INFO.

If you want to use a browser for a live preview while you keep making changes, consider adding --dirty flag to mkdocs serve command. It limits automatic regeneration to only changed files and makes browser updates much faster.

Currently we are using lychee a fast, async, stream-based link checker written in Rust. The automatic check is triggered on each push to master PR.

You can also run it locally using a docker image:

$ docker run --init -it --rm -w (pwd)−v(pwd) -v (pwd)−v(pwd):$(pwd) lycheeverse/lychee --max-redirects 10 -a 403,429,500,502,503,999 .

Please avoid using URL-related links like:

MSI PRO Z790-P

Instead, use relative links within the repository:

MSI PRO Z790-P

Make sure no TBD or TODO content is displayed

Find all occurrences:

grep -E "TBD|TODO" docs/**/*.md -r

Iterate over all occurrences and check if:

There should be no TBD or TODO visible on the website.

pre-commit hooks

pre-commit run --all-files

To skip verification

In some cases, it may be needed to skip pre-commit tests. To do that, please use:

Embedding videos

Embedding videos with in-line HTML iframe tag does not work.mkdocs-video plugin is used instead. To embed an video simply type the following in markdown:![type:video](https://www.youtube.com/embed/LXb3EKWsInQ) (example).

Embedding subscribe forms

It is possible to embed subscribe form for the selfhosted Listmonk mailing lists. To do that, paste the custom macro content in the target markdown file:

{{ subscribe_form("FORM-ID", "Button text") }}

where:

Example for ODROID H4 subpage: example code

Supported hardware

Each subsection of supported hardware should look as follows - there should be no more sections:

- 'Vendor Model':
    - 'Overview': variants/<vendor_model>/overview.md
    - 'Releases': variants/<vendor_model>/releases.md
    - 'Building manual': variants/<vendor_model>/building-manual.md
    - 'Initial deployment': variants/<vendor_model>/initial-deployment.md
    - 'Firmware update': variants/<vendor_model>/firmware-update.md
    - 'Recovery': variants/<vendor_model>/recovery.md
    - 'Hardware Configuration Matrix': variants/<vendor_model>/hardware-matrix.md
    - 'Test Matrix': variants/<vendor_model>/test-matrix.md
    - 'Security and Privacy (optional)': variants/<vendor_model>/security-and-privacy.md
    - 'Other manuals (optional)': variants/<vendor_model>/other-manuals.md
    - 'FAQ (optional)': variants/<vendor_model>/faq.md