From edf3a4d51a411f5059e3dfc715cc15354421d44f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20T=C3=A1mara?= Date: Wed, 29 Oct 2025 12:00:08 -0500 Subject: [PATCH] Add sections anchors --- content/docs/architecture.smd | 53 ++++++++++++++++++++++++++++---- content/docs/contributing.smd | 58 +++++++++++++++++++++++------------ content/docs/testing.smd | 22 ++++++++++--- 3 files changed, 102 insertions(+), 31 deletions(-) diff --git a/content/docs/architecture.smd b/content/docs/architecture.smd index 16dbcf1..51a6924 100644 --- a/content/docs/architecture.smd +++ b/content/docs/architecture.smd @@ -8,8 +8,7 @@ .githubedit = "/docs/architecture.smd", } --- -Head to: [Contribution guidelines](/docs/contributing). - b + This document describes in a general way, concepts that help to understand how the code is organized and where to look at when starting to contribute developing Flow Control. Make sure you have read @@ -19,9 +18,11 @@ and use the editor at least in flow mode. We recommend reading the in depth documentation and joining [Discord](https://discord.com/invite/4wvteUPphx) to ask from the simplest. If something does not look accurate on this documentation or -in deepwiki. Do not hesitate to ask in the channels and open a PR to -improve anything. +in deepwiki. Do not hesitate to ask in the channels and +[open a PR](https://github.com/neurocyte/flow-website/pulls) to improve +anything. +[]($section.id("internals")) ## Internals The foundational unit is the `Buffer` that holds the document in memory; @@ -40,6 +41,7 @@ hierarchy, interact with lsp and git. When flow is opened, only one active project is loaded in the current session. The `Project Manager` offers services around the set of projects. +[]($section.id("commands")) ## Editor commands and modes When a buffer is active, it has an `Editor` attached to it; an editor @@ -55,6 +57,7 @@ create a nano mode with just keybindings. In the other hand, `Vim` and `Helix` modes have particular definitions for commands that interact with the buffers, being modal editors. +[]($section.id("tui")) ## Text user interface `Tui` governs it all offering support for `Palettes` that are known @@ -63,12 +66,14 @@ through a set of `_views` (i.e. `logview`, `inputview`, `inspector_view`) and `status` (i.e. `tabs`, `clock`, `branch`, `linenum`). +[]($section.id("oses")) ## Operating systems and UI [libvaxis](https://github.com/rockorager/libvaxis) is in charge of rendering the text and all the interface in Linux, MacOS, FreeBSD, -while in Windows there is an special GUI. +and Android via Termux, while in Windows there is an special GUI. +[]($section.id("thespian")) ## Communication between components [Thespian](https://github.com/neurocyte/thespian) is in charge of @@ -83,6 +88,7 @@ perform, integration with git and running a `shell` command via a `task` all are coordinated thanks to the infrastructure that Thespian provides. +[]($section.id("languages")) ## Programming languages support There are plenty of programming languages that use tree-sitter via @@ -90,15 +96,50 @@ There are plenty of programming languages that use tree-sitter via language servers and formatters are configured via `file_type_lsp`. Currently one Language Server is supported for each language. +[]($section.id("facilities")) ## Facilities The clipboard is used for copy, paste operations and there is also support to use the system clipboard, copying and pasting to/from it. +[]($section.id("logging")) +### Logging support + Logging support offers various levels to give feedback for several actions that ease developing Flow itself and also are used to offer -feedback via `logview`. +feedback via `logview`. To view logs use `f11` to toggle the +previous messages, or alternatively, open flow with the option +`--show-logs`. +To log something import + +```zig +const log = @import("log"); +``` + +Instantiate the logger, replacing prefix with something meaningful to +differentiate from other logging messages. + +```zig +const logger = log.logger("prefix"); +defer logger.deinit(); +``` + +Log something + +```zig +logger.print("{} unsaved buffer(s) remaining", .{remaining}); +``` + +[]($section.id("show_input")) +### View key presses + +There are situations when you press some keys without the expected +behavior happening, to review if flow is getting the keys, or your desktop +environment or something else are capturing them, you will want to +invoke flow with the option `--show-input`. + +[]($section.id("next")) ## Next steps * [Guidelines for contributions](/docs/contributing) diff --git a/content/docs/contributing.smd b/content/docs/contributing.smd index e32cd98..88cb193 100644 --- a/content/docs/contributing.smd +++ b/content/docs/contributing.smd @@ -9,6 +9,7 @@ } --- +[]($section.id("request")) ## Asking for a feature Please [open an issue](https://github.com/neurocyte/flow/issues) that @@ -20,13 +21,14 @@ more information. At the end, the issues in github have more chance to get developed, given that there are plenty of things to do for this kind of software. +[]($section.id("issues")) ## Reporting a problem -If you discover a problem, or unexpected behaviour, feel free to -join [Discord](https://discord.com/invite/4wvteUPphx) to check -if there is a simple way to overcome the inconvenience or to get -some guidance. [Reporting a bug](https://github.com/neurocyte/flow/issues) -is a good way to contribute. When reporting one, it should contain: +If you discover a problem, or unexpected behaviour, feel free to join +[Discord](https://discord.com/invite/4wvteUPphx) to check if there is +a simple way to overcome the inconvenience or to get some guidance. +[Reporting a bug](https://github.com/neurocyte/flow/issues) is a good +way to contribute. When reporting one, it should contain: * Flow version. You get it with `flow --version` * What you were doing, if possible, step by step to reproduce it @@ -41,6 +43,7 @@ quick. Spreading the word is another way to contribute to Flow Code growth. +[]($section.id("developing")) ## Developing [Flow Control](https://flow-control.dev/) is programmed with @@ -60,6 +63,7 @@ agreements or find guidance. This [summary](/docs/architecture) can help on getting started to follow the codebase. +[]($section.id("coding_style")) ### Coding style Please follow what you see in the source code for functions, Structs, @@ -67,30 +71,33 @@ variables, const names, etc... Functions have descriptive names to use less time adding and maintaining comments to communicate the purpose and intent. Don't worry about commenting each function, module or parameter, there are automated tools that are currently helping -with this, take a peek on [deepwiki](https://deepwiki.com/neurocyte/flow); -if you find something inaccurate in this doc or others, do open an -issue or jump in [Discord](https://discord.com/invite/4wvteUPphx) -and comment, it's valid to -[improve too](https://github.com/neurocyte/flow-website/tree/master/content/docs/contributing.smd"). +with this, take a peek on +[deepwiki](https://deepwiki.com/neurocyte/flow); if you find something +inaccurate in this doc or others, do open an issue or jump to +[Discord](https://discord.com/invite/4wvteUPphx) and comment, it's +valid to [improve too](https://github.com/neurocyte/flow-website/tree/master/content/docs/contributing.smd"). +[]($section.id("commits")) ### Commit comments -It's better to use commits for different purposes, even if they look small and -there is a temptation to include on the same new code, fixes and refactors. Making -concise and self contained commits make review easier and future fixes possible, +It's better to use commits for different purposes, even if they look +small and there is a temptation to include on the same new code, fixes +and refactors. Making concise and self contained commits make review +easier and future fixes possible, in case of need. -Use these prefixes as much as you can, doing so helps when identifying the features -and eases the process of letting others know about what's new, fixed and help -communicate better when releasing. +Use these prefixes as much as you can, doing so helps when identifying +the features and eases the process of letting others know about what's +new, fixed and help communicate better when releasing. -* `feat:` when there is a new feature, if specific to a mode, please use -`feat: [mode]`. -* `refactor`: when reorganizing code, usually when you make something clearer -for future readers and commiters. +* `feat:` when there is a new feature, if specific to a mode, please +use `feat: [mode]`. +* `refactor`: when reorganizing code, usually when you make something +clearer for future readers and committers. * `fix:` When something changed to a more expected behaviour. * `build`: the commit doesn't change code at all. +[]($section.id("testing")) ### Testing It's possible that the test set grows as the project evolves, given @@ -99,6 +106,17 @@ opportunity to generate regressions. If you are new to zig a good place to start to learn about the codebase is [adding some tests](/docs/testing) +[]($section.id("resources")) +## Resources + +* [nerd fonts cheatsheet](https://www.nerdfonts.com/cheat-sheet): When +icons are needed, you can look for them. +* [logging](/docs/architecture#logging): When developing flow and need +to trace some messages. +* [showing key-presses](/docs/architecture#show_input): When the keyboard +don't seem to work. + +[]($section.id("next")) ## Next steps * [Join Discord](https://discord.com/invite/4wvteUPphx) diff --git a/content/docs/testing.smd b/content/docs/testing.smd index 1444870..31c48d7 100644 --- a/content/docs/testing.smd +++ b/content/docs/testing.smd @@ -17,12 +17,13 @@ and also an To work with tests you will need to: -* [Clone](https://github.com/neurocyte/flow) the repo +* [Clone](https://github.com/neurocyte/flow) the repository * Have [zig installed](https://ziglang.org/download/). Highly recommended to use [anyzig](https://github.com/marler8997/anyzig) Flow tests are placed in the directory `test`. +[]($section.id("running_tests")) ## Running the tests To run the full set of tests, inside flow, use `F5`, which runs a task that @@ -35,6 +36,7 @@ zig build test it will work if flow was invoked from the project root, which is the same place that you would normally run the tests when on the terminal. +[]($section.id("running_a_test")) ### Run a particular test To run an specific test use `Dtest-filter` option with the name of your @@ -44,6 +46,7 @@ test, i.e., for the test called **test_block_name** use: zig build test -Dtest-filter="test_block_name" ``` +[]($section.id("first_test")) ## Adding tests Tests are needed when: @@ -61,9 +64,10 @@ exercises the functionality and makes proof of it behaving as expected. Maintain the logic test as simple as possible. It's possible to add additional functions to make the tests readable and extendable though. -public functions are stratightforward tested, while there are some +public functions are straightforward tested, while there are some conventions for testing private functions. +[]($section.id("private_functions_testing")) ### Testing private functions Some internal logic of a module can be tested without the need to be @@ -106,6 +110,7 @@ try helix.test_internal.move_cursor_long_word_right_end(root, cursor, the_metric In case there is need of a new test file for concern separation, continue to the next section. +[]($section.id("new_test_file")) ## Adding a new test file Three steps are required for adding a new test file: @@ -115,6 +120,7 @@ Three steps are required for adding a new test file: 1. Optionally, make available a module to the build system for your particular test +[]($section.id("create_test_file")) ### Create the test file Place your test file under `test` directory, the name should be prefixed @@ -123,6 +129,7 @@ with `tests_`. For the rest of this section we will use as a sample `tests_project_manager.zig`. +[]($section.id("linking_tests")) ### Include the test file Tests files are linked via `test/tests.zig`, import your new test_file @@ -132,6 +139,7 @@ alphabetically as in our sample: pub const project_manager = @import("tests_project_manager.zig"); ``` +[]($section.id("import_in_build_zig")) ### Import required modules when building tests In `build.zig` import the required module under `tests.root_module`, for @@ -144,8 +152,10 @@ tests.root_module.addImport("project_manager", project_manager_mod); [Sample](https://github.com/neurocyte/flow/commit/e053a0dcf4b4c93f1ce1fe6d14a3c04e886d393c) of adding a new test file for project manager. +[]($section.id("faq")) ## FAQ on tests +[]($section.id("import_editor")) ### I need to test something that requires importing the editor ¿What do I do? There are two paths from here: @@ -154,15 +164,17 @@ There are two paths from here: 1. Extend the tests to automate via external tools +[]($section.id("lower_level")) ### Refactor to test lower level functions Refactor the functions involved in the functionality to make them -not rely directly with editor and other higher level componets, and +not rely directly with editor and other higher level components, and test the lower level ones. An example of this can be seen in commands -### Use aditional tools to test a running flow session +[]($section.id("end_to_end")) +### Use additional tools to test a running flow session Use additional tools to invoke the built editor and send keys to it, modify a file and then compare the initial contents of the file @@ -171,7 +183,7 @@ and the resulting contents of your file and the expected ones. If in doubt about how to do something, [please ask](https://discord.com/invite/4wvteUPphx). - +[]($section.id("next")) ## Next steps * [How to contribute](/docs/contributing)