neurocyte/flow-website
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add sections anchors

Browse source
This commit is contained in:
Igor Támara 2025-10-29 12:00:08 -05:00 • committed by CJ van den Berg
parent 6b5bf768f2
commit edf3a4d51a
Signed by: neurocyte
GPG key ID: 8EB1E1BB660E3FB9
3 changed files with 102 additions and 31 deletions
Download patch file Download diff file Expand all files Collapse all files

53
content/docs/architecture.smd
View file

@ -8,8 +8,7 @@
.githubedit = "/docs/architecture.smd", .githubedit = "/docs/architecture.smd",
} }
--- ---
Head to: [Contribution guidelines](/docs/contributing).
b
This document describes in a general way, concepts that help to This document describes in a general way, concepts that help to
understand how the code is organized and where to look at when starting understand how the code is organized and where to look at when starting
to contribute developing Flow Control. Make sure you have read 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 in depth documentation and joining
[Discord](https://discord.com/invite/4wvteUPphx) to ask from the [Discord](https://discord.com/invite/4wvteUPphx) to ask from the
simplest. If something does not look accurate on this documentation or 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 in deepwiki. Do not hesitate to ask in the channels and
improve anything. [open a PR](https://github.com/neurocyte/flow-website/pulls) to improve
anything.
[]($section.id("internals"))
## Internals ## Internals
The foundational unit is the `Buffer` that holds the document in memory; 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` active project is loaded in the current session. The `Project Manager`
offers services around the set of projects. offers services around the set of projects.
[]($section.id("commands"))
## Editor commands and modes ## Editor commands and modes
When a buffer is active, it has an `Editor` attached to it; an editor 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 `Helix` modes have particular definitions for commands that interact
with the buffers, being modal editors. with the buffers, being modal editors.
[]($section.id("tui"))
## Text user interface ## Text user interface
`Tui` governs it all offering support for `Palettes` that are known `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`, `inspector_view`) and `status` (i.e. `tabs`, `clock`, `branch`,
`linenum`). `linenum`).
[]($section.id("oses"))
## Operating systems and UI ## Operating systems and UI
[libvaxis](https://github.com/rockorager/libvaxis) is in charge of [libvaxis](https://github.com/rockorager/libvaxis) is in charge of
rendering the text and all the interface in Linux, MacOS, FreeBSD, 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 ## Communication between components
[Thespian](https://github.com/neurocyte/thespian) is in charge of [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 `task` all are coordinated thanks to the infrastructure that
Thespian provides. Thespian provides.
[]($section.id("languages"))
## Programming languages support ## Programming languages support
There are plenty of programming languages that use tree-sitter via 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`. language servers and formatters are configured via `file_type_lsp`.
Currently one Language Server is supported for each language. Currently one Language Server is supported for each language.
[]($section.id("facilities"))
## Facilities ## Facilities
The clipboard is used for copy, paste operations and there is also The clipboard is used for copy, paste operations and there is also
support to use the system clipboard, copying and pasting to/from it. 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 Logging support offers various levels to give feedback for several
actions that ease developing Flow itself and also are used to offer 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 ## Next steps
* [Guidelines for contributions](/docs/contributing) * [Guidelines for contributions](/docs/contributing)

58
content/docs/contributing.smd
View file

@ -9,6 +9,7 @@
} }
--- ---
[]($section.id("request"))
## Asking for a feature ## Asking for a feature
Please [open an issue](https://github.com/neurocyte/flow/issues) that 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 chance to get developed, given that there are plenty of things
to do for this kind of software. to do for this kind of software.
[]($section.id("issues"))
## Reporting a problem ## Reporting a problem
If you discover a problem, or unexpected behaviour, feel free to If you discover a problem, or unexpected behaviour, feel free to join
join [Discord](https://discord.com/invite/4wvteUPphx) to check [Discord](https://discord.com/invite/4wvteUPphx) to check if there is
if there is a simple way to overcome the inconvenience or to get a simple way to overcome the inconvenience or to get some guidance.
some guidance. [Reporting a bug](https://github.com/neurocyte/flow/issues) [Reporting a bug](https://github.com/neurocyte/flow/issues) is a good
is a good way to contribute. When reporting one, it should contain: way to contribute. When reporting one, it should contain:
* Flow version. You get it with `flow --version` * Flow version. You get it with `flow --version`
* What you were doing, if possible, step by step to reproduce it * 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. Spreading the word is another way to contribute to Flow Code growth.
[]($section.id("developing"))
## Developing ## Developing
[Flow Control](https://flow-control.dev/) is programmed with [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 This [summary](/docs/architecture) can help on getting started to
follow the codebase. follow the codebase.
[]($section.id("coding_style"))
### Coding style ### Coding style
Please follow what you see in the source code for functions, Structs, 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 use less time adding and maintaining comments to communicate the
purpose and intent. Don't worry about commenting each function, module purpose and intent. Don't worry about commenting each function, module
or parameter, there are automated tools that are currently helping or parameter, there are automated tools that are currently helping
with this, take a peek on [deepwiki](https://deepwiki.com/neurocyte/flow); with this, take a peek on
if you find something inaccurate in this doc or others, do open an [deepwiki](https://deepwiki.com/neurocyte/flow); if you find something
issue or jump in [Discord](https://discord.com/invite/4wvteUPphx) inaccurate in this doc or others, do open an issue or jump to
and comment, it's valid to [Discord](https://discord.com/invite/4wvteUPphx) and comment, it's
[improve too](https://github.com/neurocyte/flow-website/tree/master/content/docs/contributing.smd"). valid to [improve too](https://github.com/neurocyte/flow-website/tree/master/content/docs/contributing.smd").
[]($section.id("commits"))
### Commit comments ### Commit comments
It's better to use commits for different purposes, even if they look small and It's better to use commits for different purposes, even if they look
there is a temptation to include on the same new code, fixes and refactors. Making small and there is a temptation to include on the same new code, fixes
concise and self contained commits make review easier and future fixes possible, and refactors. Making concise and self contained commits make review
easier and future fixes possible,
in case of need. in case of need.
Use these prefixes as much as you can, doing so helps when identifying the features Use these prefixes as much as you can, doing so helps when identifying
and eases the process of letting others know about what's new, fixed and help the features and eases the process of letting others know about what's
communicate better when releasing. new, fixed and help communicate better when releasing.
* `feat:` when there is a new feature, if specific to a mode, please use * `feat:` when there is a new feature, if specific to a mode, please
`feat: [mode]`. use `feat: [mode]`.
* `refactor`: when reorganizing code, usually when you make something clearer * `refactor`: when reorganizing code, usually when you make something
for future readers and commiters. clearer for future readers and committers.
* `fix:` When something changed to a more expected behaviour. * `fix:` When something changed to a more expected behaviour.
* `build`: the commit doesn't change code at all. * `build`: the commit doesn't change code at all.
[]($section.id("testing"))
### Testing ### Testing
It's possible that the test set grows as the project evolves, given 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 place to start to learn about the codebase is
[adding some tests](/docs/testing) [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 ## Next steps
* [Join Discord](https://discord.com/invite/4wvteUPphx) * [Join Discord](https://discord.com/invite/4wvteUPphx)

22
content/docs/testing.smd
View file

@ -17,12 +17,13 @@ and also an
To work with tests you will need to: 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 * Have [zig installed](https://ziglang.org/download/). Highly recommended to use
[anyzig](https://github.com/marler8997/anyzig) [anyzig](https://github.com/marler8997/anyzig)
Flow tests are placed in the directory `test`. Flow tests are placed in the directory `test`.
[]($section.id("running_tests"))
## Running the tests ## Running the tests
To run the full set of tests, inside flow, use `F5`, which runs a task that 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 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. place that you would normally run the tests when on the terminal.
[]($section.id("running_a_test"))
### Run a particular test ### Run a particular test
To run an specific test use `Dtest-filter` option with the name of your 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" zig build test -Dtest-filter="test_block_name"
``` ```
[]($section.id("first_test"))
## Adding tests ## Adding tests
Tests are needed when: 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 Maintain the logic test as simple as possible. It's possible to add
additional functions to make the tests readable and extendable though. 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. conventions for testing private functions.
[]($section.id("private_functions_testing"))
### Testing private functions ### Testing private functions
Some internal logic of a module can be tested without the need to be 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 In case there is need of a new test file for concern separation, continue
to the next section. to the next section.
[]($section.id("new_test_file"))
## Adding a new test file ## Adding a new test file
Three steps are required for 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 1. Optionally, make available a module to the build system
for your particular test for your particular test
[]($section.id("create_test_file"))
### Create the test file ### Create the test file
Place your test file under `test` directory, the name should be prefixed 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 For the rest of this section we will use as a sample
`tests_project_manager.zig`. `tests_project_manager.zig`.
[]($section.id("linking_tests"))
### Include the test file ### Include the test file
Tests files are linked via `test/tests.zig`, import your new 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"); pub const project_manager = @import("tests_project_manager.zig");
``` ```
[]($section.id("import_in_build_zig"))
### Import required modules when building tests ### Import required modules when building tests
In `build.zig` import the required module under `tests.root_module`, for 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) [Sample](https://github.com/neurocyte/flow/commit/e053a0dcf4b4c93f1ce1fe6d14a3c04e886d393c)
of adding a new test file for project manager. of adding a new test file for project manager.
[]($section.id("faq"))
## FAQ on tests ## FAQ on tests
[]($section.id("import_editor"))
### I need to test something that requires importing the editor ¿What do I do? ### I need to test something that requires importing the editor ¿What do I do?
There are two paths from here: 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 1. Extend the tests to automate via external tools
[]($section.id("lower_level"))
### Refactor to test lower level functions ### Refactor to test lower level functions
Refactor the functions involved in the functionality to make them 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. test the lower level ones.
An example of this can be seen in commands 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 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 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, If in doubt about how to do something,
[please ask](https://discord.com/invite/4wvteUPphx). [please ask](https://discord.com/invite/4wvteUPphx).
[]($section.id("next"))
## Next steps ## Next steps
* [How to contribute](/docs/contributing) * [How to contribute](/docs/contributing)