diff --git a/README.md b/README.md index 6327d4f..156377e 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ added. 1. Update the file `contrib/symbolnerdfontmonolist.txt` adding the unicode 2. Add the reference to assets/css/webfont.css 3. Use it the same as layouts/templates/base.html navbar -4. Update the fonts installing (uv pip install fonttools) with: +4. Update the fonts(to install the tool `uv pip install fonttools`) with: ```python pyftsubset contrib/fonts/nerdfonts/SymbolsNerdFontMono-Regular.ttf --unicodes-file=contrib/symbolnerdfontmonolist.txt --output-file=assets/fonts/SymbolsNerdFontMono-Regular.ttf @@ -37,9 +37,27 @@ If the icon you want to use from nerdonfts is not present in contrib/fonts/nerdf get it from https://github.com/ryanoasis/nerd-fonts/releases/download/v3.4.0/NerdFontsSymbolsOnly.zip and update contrib to ease later needings. +## Custom frontmatter + +Some [custom frontmatter](https://zine-ssg.io/docs/supermd/#frontmatter) fields are being used on the docs + +### githubedit (Optional) +Directs to contribute editing this documentation. Used by `layout/tutorial.shtml`. + +```ziggy + .githubedit** = "/docs/testing.md", +``` + +### codepath (Optional) +Links to relevant source code on the current doc. Used by `layout/tutorial.shtml`. + +```ziggy + .codepath ="test", +``` + ## Resources -* [Monospace Web Theme](https://owickstrom.github.io/the-monospace-web/) * [Zine](https://zine-ssg.io/docs/) * [Flow Control Editor](https://github.com/neurocyte/flow) * [NerdFonts](https://www.nerdfonts.com/cheat-sheet) +* [Monospace Web Theme](https://owickstrom.github.io/the-monospace-web/) diff --git a/assets/css/index.css b/assets/css/index.css index 48c045b..7e4136f 100644 --- a/assets/css/index.css +++ b/assets/css/index.css @@ -485,3 +485,10 @@ label input { .debug-toggle-label { text-align: right; } + +div nav { + text-align: right; +} +div.tutnav p { + text-align: center; +} diff --git a/assets/css/webfont.css b/assets/css/webfont.css index 8a0529c..94212bf 100644 --- a/assets/css/webfont.css +++ b/assets/css/webfont.css @@ -40,3 +40,9 @@ .nf-fa-people_carry_box:before { content: "\eda2"; } +.nf-dev-zig:before { + content: "\e8ef"; +} +.nf-fa-edit:before { + content: "\f044"; +} diff --git a/assets/fonts/SymbolsNerdFontMono-Regular.ttf b/assets/fonts/SymbolsNerdFontMono-Regular.ttf index c5622a1..e45ec1d 100644 Binary files a/assets/fonts/SymbolsNerdFontMono-Regular.ttf and b/assets/fonts/SymbolsNerdFontMono-Regular.ttf differ diff --git a/content/docs/architecture.smd b/content/docs/architecture.smd index b0e2658..51a6924 100644 --- a/content/docs/architecture.smd +++ b/content/docs/architecture.smd @@ -4,7 +4,9 @@ .author = "Igor Támara", .layout = "tutorial.shtml", .draft = false, -.custom = { .githubedit = "https://github.com/neurocyte/flow-website/tree/master/content/docs/architecture.smd"}, +.custom = { + .githubedit = "/docs/architecture.smd", +} --- This document describes in a general way, concepts that help to @@ -16,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; @@ -37,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 @@ -52,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 @@ -60,22 +66,29 @@ 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 processes synchronization and allows sending messages between different flow components, for example, when a widget needs updating information from changing states of internal data and -when components or external processes take time. For example, -tree-sitter queries to highlight the current file of a particular -language, LSPs, git, running a `shell` command via a `task`. +when components or external processes take time and need to return +an answer, all this without blocking the user interface. Tree-sitter +queries to highlight the current file of a particular +language and LSPs usually take time by the nature of operations they +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 @@ -83,14 +96,52 @@ 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. -Logging support offers various levels to give feedback for various +[]($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 -We have some [contribution guidelines](/docs/contributing). \ No newline at end of file +```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) +* [Take a peek on testing](/docs/testing) +* [Back to docs](/docs) \ No newline at end of file diff --git a/content/docs/contributing.smd b/content/docs/contributing.smd index 5ee9de7..88cb193 100644 --- a/content/docs/contributing.smd +++ b/content/docs/contributing.smd @@ -4,9 +4,12 @@ .author = "Igor Támara", .layout = "tutorial.shtml", .draft = false, -.custom = { .githubedit = "https://github.com/neurocyte/flow-website/tree/master/content/docs/contributing.smd"}, +.custom = { + .githubedit = "/docs/contributing.smd", +} --- +[]($section.id("request")) ## Asking for a feature Please [open an issue](https://github.com/neurocyte/flow/issues) that @@ -18,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 @@ -39,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 @@ -58,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, @@ -65,39 +71,55 @@ 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 that the amount of relationships among components increase the -opportunity to generate regressions. +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) -## Getting in touch. +[]($section.id("resources")) +## Resources -[Discord](https://discord.com/invite/4wvteUPphx) and -[Github issues](https://github.com/neurocyte/flow/issues) are the -main channels to do so. +* [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) +* [Fill an issue](https://github.com/neurocyte/flow/issues) +* [Add some tests](/docs/testing) +* [Back to architecture](/docs/architecture) diff --git a/content/docs/testing.smd b/content/docs/testing.smd new file mode 100644 index 0000000..31c48d7 --- /dev/null +++ b/content/docs/testing.smd @@ -0,0 +1,191 @@ +--- +.title = "Testing", +.date = @date("2025-10-20T00:00:00"), +.author = "Igor Támara", +.layout = "tutorial.shtml", +.draft = false, +.custom = { + .githubedit = "/docs/testing.md", + .codepath ="test", +}, +--- +Currently flow tests are aimed to work as unit tests, it always is a good +idea to review the +[zig tests documentation](https://ziglang.org/documentation/master/#Zig-Test) +and also an +[introduction to testing](https://pedropark99.github.io/zig-book/Chapters/03-unittests.html). + +To work with tests you will need to: + +* [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 +invokes: + +``` +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 +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: + +* There is some logic that might be difficult to understand given it's +nature, for example, when there are a lot of branching +* You find something that could be changed in the future affecting the +current behavior +* A bug is fixed +* A defined behavior could be thought different, for example when in a mode, +it was defined that something might diverge from other programs. + +Tests are placed under `test` directory. Add your test in the file that +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 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 +exposed to other modules. + +In such cases the module that has the logic should provide a pub +`test_internal`, by convention, exposing the target functionalities to +be tested. + +For example in `src/tui/mode/helix.zig`, `test_internal` exposes the private +function + +```zig +fn move_cursor_long_word_right_end(root: Buffer.Root, cursor: *Cursor, metrics: Buffer.Metrics) error{Stop}!void +``` + +with + +```zig +pub const test_internal = struct { + pub const move_cursor_long_word_right = private.move_cursor_long_word_right; +. +. +. +}; +``` + +And in `test/tests_helix.zig`, helix is imported as + +```zig +const helix = @import("tui").exports.mode.helix; +``` + +Later on using the function `move_cursor_long_word_right` as + +```zig +try helix.test_internal.move_cursor_long_word_right_end(root, cursor, the_metrics); +``` + +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: + +1. Create a new test file +1. Include the test to the set of tests +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 +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 +alphabetically as in our sample: + +```zig +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 +the current example: + +```zig +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: + +1. Refactor your code to test the lower level functions +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 components, and +test the lower level ones. + +An example of this can be seen in commands + +[]($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 +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) +* [User Documentation](/docs) +* [Other Flow topics](/docs/architecture) \ No newline at end of file diff --git a/contrib/symbolnerdfontmonolist.txt b/contrib/symbolnerdfontmonolist.txt index 9022134..591ac35 100644 --- a/contrib/symbolnerdfontmonolist.txt +++ b/contrib/symbolnerdfontmonolist.txt @@ -4,3 +4,5 @@ U+eadc U+f409 U+e889 U+eda4 +U+e8ef +U+f044 diff --git a/layouts/tutorial.shtml b/layouts/tutorial.shtml index 77da689..e6ee2ce 100644 --- a/layouts/tutorial.shtml +++ b/layouts/tutorial.shtml @@ -2,10 +2,22 @@ -

-
-
-

If you find anything that could be better, because it does not reflect - what happens with flow or can be explain better, don't hesitate to - improve me.

- \ No newline at end of file +

+
+ +
+ +
+