Repository files navigation

This repository contains source code for the Dasharo documentation webpage

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

virtualenv -p$(which python3) venvsource venv/bin/activatepip install -r requirements.txtmkdocs serve

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

If the following error occursOSError: [Errno 98] Address already in use, tryusing a different address by running the commandmkdocs serve -a localhost:12345 (the number is random).

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

It is also important to read through the console output after runningmkdocs serve. You should definitely eliminate anyWARNINGs related to yourcontribution before submitting it for review, and you should consider applyingsuggestions marked asINFO.

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

If you need to update the environment (for example, ifrequirements.txt wasupdated), just runrm -r venv and re-run the steps above.

Currently we are usinglychee a fast,async, stream-based link checker written in Rust. The automatic check istriggered 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):$(pwd) lycheeverse/lychee    --max-redirects 10 -a 403,429,500,502,503,999.

Please avoid using URL-related links like:

[MSI PRO Z790-P](../../unified/msi/overview)

Instead, use relative links within the repository:

[MSI PRO Z790-P](../unified/msi/overview.md)

Find all occurrences:

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

Iterate over all occurrences and check if:

• file, where TBD or TODO occurs, is displayed (included in nav section ofmkdocs.yml)
• TBD or TODO is visible on the website

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

• Install pre-commit, if youfollowedlocal build procedurepre-commit should beinstalled

• Install go

• Install hooks into repo:

pre-commit install

• Enjoy automatic checks on eachgit commit action!

• (Optional) Run hooks on all files (for example, when adding new hooks orconfiguring existing ones):

pre-commit run --all-files

In some cases, it may be needed to skippre-commit tests. To do that, pleaseuse:

git commit --no-verify

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

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

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

where:

• FORM-ID - target mailing list form ID that can be foundhere(check target list and copychecked_value= content from Form HTML).
• Button text - text to be shown on the button.

Example for ODROID H4 subpage:example code

Each subsection of supported hardware should look as follows - there should beno 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

• Vendor can have multiple meanings, but it can be a vendor who sells theplatform, OEM or ODM. We tend to follow the naming convention used incoreboot or other open-source firmware projects. We can consider adjustmentof the name for SEO reasons, community, or customer demand.
• Model in most cases it would include some literal and number, we don't wantto overload the reader with very precise IDs. As for vendors we try to reuseexisting open-source firmware conventions, but if needed we can adjust themodel name.
• Overview presents general information related to Dasharo, history, map ofsubsections, marketing materials, and press release links.
• Releases section where all binaries are provided in a standardized way.
• Building manual section provides instructions on how to build release anddebug binaries in a reproducible manner.
• Firmware update section explains all methods to update the firmware. Ifadditional steps are needed to perform updates between specific versions it,should also be covered in this section.
• Recovery section describes what to do in case of various error signaturese.g. platform not booting or hanging in a particular place.
• Hardware Configuration Matrix - presents the configuration used in Dasharolabs to perform validation as well as a community-contributed hardwarecompatibility reports, which present CPUs, GPUs, memory modules, and othercomponents tested by community.
• Test Matrix - presents a list of tests that we execute during the releaseprocess.
• Community Test Results - an optional section that presents test resultscontributed by the community.
• Security and Privacy - an optional section that provides security-relatedinformation, like the size of the trusted computing base (via DasharoOpenness Score), manuals on how to use verified boot, measured boot, or UEFISecure Boot.
• Other manuals - an optional section that provides other manuals, such as:how to enable fan control, update EC controller, customize logo etc.
• FAQ - frequently asked questions related to a given hardware platform andDasharo support for it.