Welcome to the Black Magic Debug website sources.

Feel free to open issues and pull requests for this repository to add and improve the Black Magic Debug project documentation.

Technical overview

The page is a static autogenerated page using Zola documentation generator. The resulting page is then deployed to Codeberg pages using Codeberg actions.

All pages except the autogenerated code documentation are all written in markdown using the myst_parser sphinx plugin.

Structure

The page is divided into topic sections, autogenerated API documentation (TODO) and a blog (TODO).

Each topic section is in it's own subdirectory.

Local preview/testing

When you write contributions to the website you can autogenerate the page locally on your own computer and preview it locally.

You should get Zola and then all you need to do is run make in the root directory of the repository.

This should generate the pinout diagrams and start zola serve which will present a website preview.

fork the repository to your personal account

If you want to contribute to the documentation it is probably a good idea to fork the black-magic-org Codeberg repository first.

clone the website sources

Now that you have a fork clone it and create a working branch.

git clone <path to your user>/black-magic-org
cd black-magic-org
git checkout -b feature/adding-more-docs

Note: Obviously feature/adding-more-docs is a placeholder. The should call it something appropriate to your addition. The convention in black-magic is to use feature/ and fix/ prefixes to the branch names to indicate what kind of an addition this new work branch will be.

edit pages

Now every time you edit one of the page markdown files the page will automatically update.

Keep in mind that when you create a new page the live_preload does not always pick it up, so you might have to restart it from time to time.

contribute

We are looking forward to your contributions! :D