From ccb6c1c36845026914f4ef3a3a6b2457bea94482 Mon Sep 17 00:00:00 2001 From: Joshua Thijssen Date: Mon, 30 Sep 2024 13:18:38 +0200 Subject: [PATCH 1/2] Added / updated more documentation --- CONTRIBUTING.md | 4 +-- README.md | 5 ++-- docs/crates.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 82 insertions(+), 6 deletions(-) create mode 100644 docs/crates.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5f11722df..b0bb6e7ae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,8 +6,6 @@ This is an initial (but not fully complete) contribution guide. **Useful Links for Developers:** * [Developer Chat](https://chat.developer.gosub.io/) * [Wiki](https://wiki.developer.gosub.io/) -* [API Docs](https://docs.developer.gosub.io/) -* [Benchmarks](https://bench.developer.gosub.io/) ## Contents * [Introduction to the Makefiles](#introduction-to-the-makefiles) @@ -103,7 +101,7 @@ At this point, there are a few main paths: * Study the codebase * If you're not exactly sure what to do, it might be a good opportunity to spend some time sifting through the codebase and understanding how things are structured. * Issue tackling - * We don't have a high volume of issues at the moment, but there may be some that a new contributer can pick up! + * We don't have a high volume of issues at the moment, but there may be some that a new contributor can pick up! * Specification compliance * We are not completely in compliance with certain specifications (CSS, DOM) and could likely use some help there. * Write tests diff --git a/README.md b/README.md index 9d12c64be..bdcd41dfc 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,6 @@ This repository is part of the Gosub browser engine project. This is the main en - Networking stack - Rendering engine - JS bridge -- C Bindings More will follow as the engine grows. The idea is that this engine will receive some kind of stream of bytes (most likely from a socket or file) and parse this into a valid HTML5 document tree and CSS stylesheets. @@ -34,7 +33,7 @@ tree can be modified by JS. ## Status > This project is in its infancy. There is no usable browser yet. However, you can look at simple html pages and parse -> them into a document tree. +> them into a document tree and do some initial rendering. We can parse HTML5 and CSS3 files into a document tree or the respective css tree. This tree can be shown in the terminal or be rendered in a very unfinished renderer. Our renderer cannot render everything yet, but it can render simple html @@ -120,4 +119,4 @@ building small proof-of-concepts and figuring out what needs to be done next. Mu of the project will be non-coding. We do like to hear from you if you are interested in contributing to the project and you can join us currently at -our [Zulip chat](https://chat.developer.gosub.io)! +our [Zulip chat](https://chat.developer.gosub.io)! \ No newline at end of file diff --git a/docs/crates.md b/docs/crates.md new file mode 100644 index 000000000..b02327e3c --- /dev/null +++ b/docs/crates.md @@ -0,0 +1,79 @@ +# Gosub crates + +The engine is split up in a few different crates. This is done to keep the codebase clean and to allow for easier testing and development. The following crates are currently available: + +* gosub_config +* gosub_css3 +* gosub_html5 +* gosub_jsapi +* gosub_net +* gosub_render_backend +* gosub_render_utils +* gosub_renderer +* gosub_shared +* gosub_svg +* gosub_taffy +* gosub_testing +* gosub_typeface +* gosub_useragent +* gosub_v8 +* gosub_vello +* gosub_webexecutor +* gosub_webinterop + +Some of the crates are dependent on other crates, but we aim to be as modular as possible. The `gosub_shared` crate is a crate that is used by most of the other crates and contains shared code and data structures. + + +## gosub_config +This crate contains a configuration system that is used by the engine. It can store information in a store (for instance, sqlite, or simply json) and can + +## gosub_css3 +This crate contains a CSS3 parser that can parse CSS3 stylesheets and can be used to style HTML5 documents. It also holds the parser to parse the CSS3 property syntax in order to validate Css properties. + +## gosub_html5 +The main html5 tokenizer and parser. It also includes the main "Document" object that is used to represent the DOM tree and its node elements + +## gosub_jsapi +This crate contains Javascript api's that are usable in the browser. For instance, the console API, the fetch API, the DOM API, etc. + +## gosub_net +This crate contains the network stack that is used to fetch resources from the web. It can fetch resources from the web, but also from the local filesystem. Currently hosting a DNS system that we can use for resolving domain names over different kind of protocols. + +## gosub_render_backend +TBD + +## gosub_render_utils +TBD + +## gosub_renderer +TBD + +## gosub_shared +Some of the code and data structures that will be used throughout different crates are stored here. It also holds the traits that are used to implement the different parts of the engine. + +## gosub_svg +TBD + +## gosub_taffy +TBD + +## gosub_testing +A dedicated crate for testing some of the engine. This will allow to easily test the different parts of the engine, most notably the html5 tokenizer and parser. + +## gosub_typeface +TBD + +## gosub_useragent +This crate keeps a simple application with event loop renders html5 documents. It can be seen as a very simple browser. Ultimately, this crate will be removed in favor of an external application that will use the engine. + +## gosub_v8 +Gosub bindings to the V8 javascript engine. + +## gosub_vello +TBD + +## gosub_webexecutor +System to execute javascript. This could also be used for executing other languages in the future, like lua. + +## gosub_webinterop +TBD \ No newline at end of file From 791f50fa290e043abc93a25edc45c307bc5079c9 Mon Sep 17 00:00:00 2001 From: Shark Date: Mon, 30 Sep 2024 20:08:09 +0200 Subject: [PATCH 2/2] add missing crate docs --- docs/crates.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/crates.md b/docs/crates.md index b02327e3c..0a0d06003 100644 --- a/docs/crates.md +++ b/docs/crates.md @@ -40,28 +40,28 @@ This crate contains Javascript api's that are usable in the browser. For instanc This crate contains the network stack that is used to fetch resources from the web. It can fetch resources from the web, but also from the local filesystem. Currently hosting a DNS system that we can use for resolving domain names over different kind of protocols. ## gosub_render_backend -TBD +This crate contains trait definitions of the render backend and some more layout. ## gosub_render_utils -TBD +This crate contains implementations of the render tree and some other utilities, for instance for resolving mouse positions back to elements. ## gosub_renderer -TBD +This crate contains the actual renderer. It uses the traits defined in the `gosub_render_backend` crate to render a html document. ## gosub_shared Some of the code and data structures that will be used throughout different crates are stored here. It also holds the traits that are used to implement the different parts of the engine. ## gosub_svg -TBD +Implementation of the SVG Document for `usvg` and optionally the `resvg` crates, used for SVG rendering. ## gosub_taffy -TBD +Implementation of layout traits for the `taffy` layouting system. ## gosub_testing A dedicated crate for testing some of the engine. This will allow to easily test the different parts of the engine, most notably the html5 tokenizer and parser. ## gosub_typeface -TBD +Currently doesn't do much, but it is used to store fallback fonts and the `Font` trait ## gosub_useragent This crate keeps a simple application with event loop renders html5 documents. It can be seen as a very simple browser. Ultimately, this crate will be removed in favor of an external application that will use the engine. @@ -70,10 +70,10 @@ This crate keeps a simple application with event loop renders html5 documents. I Gosub bindings to the V8 javascript engine. ## gosub_vello -TBD +Implementation of a RenderBackend for the `vello` crate ## gosub_webexecutor System to execute javascript. This could also be used for executing other languages in the future, like lua. ## gosub_webinterop -TBD \ No newline at end of file +Proc macro to easily pass functions and define APIs to javascript, wasm or lua and others. \ No newline at end of file