bendelathouwer/black-magic-org

The Black Magic Project Website

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 sphinx python documentation generator. The resulting page is then deployed to GitHub pages using GitHub 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.

If you have python3 available on your system the process is fairly simple.

NOTE: On MacOS you will also need to install the following brew packages:

brew install python3
brew install cairo
brew install pango
brew install python-tk

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 GitHub 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.

create and activate venv

This venv is local to the repository as it will be pretty specific to this project.

python3 -m venv env
source env/bin/activate

update pip

pip install --upgrade pip

install dependencies

pip install -r requirements.txt

start previewer

We have a small script that starts a page preview server locally on your machine.

$ python ./run_livereload.py
[SNIP...] here is a bunch of output from make html output to make sure the static
[SNIP...] page is built before starting the livereload server
[I 200910 13:47:15 server:335] Serving on http://127.0.0.1:5500
[I 200910 13:47:15 handlers:62] Start watching changes
[I 200910 13:47:15 handlers:64] Start detecting changes

Now you can point your browser to http://127.0.0.1:5500, and you should see the Black Magic Debug website.

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