From a01eb692963a796b9cd4b799b1a47f27fd007f67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20T=C3=A1mara?= Date: Tue, 21 Oct 2025 18:48:13 -0500 Subject: [PATCH 01/10] Improve doc navigation --- assets/css/index.css | 7 +++++++ layouts/tutorial.shtml | 37 ++++++++++++++++++++++++++++++------- 2 files changed, 37 insertions(+), 7 deletions(-) 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/layouts/tutorial.shtml b/layouts/tutorial.shtml index 77da689..009b00a 100644 --- a/layouts/tutorial.shtml +++ b/layouts/tutorial.shtml @@ -2,10 +2,33 @@ -

-
-
-

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 +

+
+ +
+

+ ← + + ; + ; + + + + Code + Code + → + → +

+
+ +
+ +
+ From 5be5f003c8c2abe0aeeb5c054eb5688b7d857d92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20T=C3=A1mara?= Date: Tue, 21 Oct 2025 18:48:36 -0500 Subject: [PATCH 02/10] Add testing section --- content/docs/architecture.smd | 27 ++++++++----- content/docs/contributing.smd | 14 +++++-- content/docs/testing.smd | 76 +++++++++++++++++++++++++++++++++++ 3 files changed, 105 insertions(+), 12 deletions(-) create mode 100644 content/docs/testing.smd diff --git a/content/docs/architecture.smd b/content/docs/architecture.smd index b0e2658..4275760 100644 --- a/content/docs/architecture.smd +++ b/content/docs/architecture.smd @@ -4,9 +4,17 @@ .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 = "https://github.com/neurocyte/flow-website/tree/master/content/docs/architecture.smd", + .prevurl = "https://github.com/neurocyte/flow", + .prevtext = "Code", + .nexturl = "/docs/contributing", + .nexttext = "Contributing", + .topurl = "/docs/", + .toptext = "Docs", +} --- - +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 @@ -72,9 +80,13 @@ while in Windows there is an special GUI. 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. ## Programming languages support @@ -88,9 +100,6 @@ Currently one Language Server is supported for each language. 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 +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`. - - -We have some [contribution guidelines](/docs/contributing). \ No newline at end of file diff --git a/content/docs/contributing.smd b/content/docs/contributing.smd index 5ee9de7..4a10e40 100644 --- a/content/docs/contributing.smd +++ b/content/docs/contributing.smd @@ -4,7 +4,14 @@ .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 = "https://github.com/neurocyte/flow-website/tree/master/content/docs/contributing.smd", + .nexturl = "/docs/testing", + .nexttext = "Testing", + .topurl = "/docs/", + .toptext = "Docs", + .prevurl = "/docs/architecture", + .prevtext = "Architecture", +} --- ## Asking for a feature @@ -93,11 +100,12 @@ for future readers and commiters. 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. [Discord](https://discord.com/invite/4wvteUPphx) and [Github issues](https://github.com/neurocyte/flow/issues) are the main channels to do so. - diff --git a/content/docs/testing.smd b/content/docs/testing.smd new file mode 100644 index 0000000..b621101 --- /dev/null +++ b/content/docs/testing.smd @@ -0,0 +1,76 @@ +--- +.title = "Testing", +.date = @date("2025-10-20T00:00:00"), +.author = "Igor Támara", +.layout = "tutorial.shtml", +.draft = false, +.custom = { + .githubedit = "https://github.com/neurocyte/flow-website/tree/master/content/docs/testing.md", + .prevurl = "/docs/contributing", + .prevtext = "Contributing", + .topurl = "/docs/architecture", + .toptext = "Architecture", + .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 repo +* Have [zig installed](https://ziglang.org/download/). Highly recommended to use +[anyzig](https://github.com/marler8997/anyzig) + +## Running the tests + +To run the full set of tests, inside flow, use F6, which invokes + +``` +zig build test +``` + +it will work if flow was invoked from the root flow when you cloned the repo. + +## Run a particular test + +To run a particular test use + +``` +zig build test -Dtest-filter="test_block_name" +``` + +## Adding a new test file + +Tests files are linked via `tests.zig` and if your file test requires +to import an additional module from flow, it can be done via the +corresponding test step in `build.zig`, look for `test_step.dependOn` +to find out where to make the module available for your test case +need. + +## I need to test something that requires importing the editor + +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 + + +### 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 +test the lower level ones. + +### Use aditional 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). From cdf398681e8582d219053ffc86c6d598bea841d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20T=C3=A1mara?= Date: Tue, 21 Oct 2025 19:04:32 -0500 Subject: [PATCH 03/10] Improve links avoiding brands --- content/docs/architecture.smd | 3 ++- content/docs/contributing.smd | 3 ++- content/docs/testing.smd | 2 +- layouts/tutorial.shtml | 9 +++++++-- 4 files changed, 12 insertions(+), 5 deletions(-) diff --git a/content/docs/architecture.smd b/content/docs/architecture.smd index 4275760..8d2f3a1 100644 --- a/content/docs/architecture.smd +++ b/content/docs/architecture.smd @@ -4,7 +4,8 @@ .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", .prevurl = "https://github.com/neurocyte/flow", .prevtext = "Code", .nexturl = "/docs/contributing", diff --git a/content/docs/contributing.smd b/content/docs/contributing.smd index 4a10e40..5bc2b45 100644 --- a/content/docs/contributing.smd +++ b/content/docs/contributing.smd @@ -4,7 +4,8 @@ .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", .nexturl = "/docs/testing", .nexttext = "Testing", .topurl = "/docs/", diff --git a/content/docs/testing.smd b/content/docs/testing.smd index b621101..3bfa61a 100644 --- a/content/docs/testing.smd +++ b/content/docs/testing.smd @@ -5,7 +5,7 @@ .layout = "tutorial.shtml", .draft = false, .custom = { - .githubedit = "https://github.com/neurocyte/flow-website/tree/master/content/docs/testing.md", + .githubedit = "/docs/testing.md", .prevurl = "/docs/contributing", .prevtext = "Contributing", .topurl = "/docs/architecture", diff --git a/layouts/tutorial.shtml b/layouts/tutorial.shtml index 009b00a..bd933c0 100644 --- a/layouts/tutorial.shtml +++ b/layouts/tutorial.shtml @@ -25,10 +25,15 @@ From cc917d74890a2095b5b5eeee6a1e661147d88d57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20T=C3=A1mara?= Date: Tue, 28 Oct 2025 08:57:01 -0500 Subject: [PATCH 04/10] Explicit content for testing --- content/docs/testing.smd | 122 +++++++++++++++++++++++++++++++++++---- 1 file changed, 111 insertions(+), 11 deletions(-) diff --git a/content/docs/testing.smd b/content/docs/testing.smd index 3bfa61a..f76ca41 100644 --- a/content/docs/testing.smd +++ b/content/docs/testing.smd @@ -19,40 +19,138 @@ idea to review the 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 repo * 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`. + ## Running the tests -To run the full set of tests, inside flow, use F6, which invokes +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 root flow when you cloned the repo. +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. -## Run a particular test +### Run a particular test -To run a particular test use +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" ``` +## 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 stratightforward tested, while there are some +conventions for testing private functions. + +### 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. + ## Adding a new test file -Tests files are linked via `tests.zig` and if your file test requires -to import an additional module from flow, it can be done via the -corresponding test step in `build.zig`, look for `test_step.dependOn` -to find out where to make the module available for your test case -need. +Three steps are required for adding a new test file: -## I need to test something that requires importing the editor +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 + +### 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`. + +### 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"); +``` + +### 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. + +## FAQ on tests + +### I need to test something that requires importing the editor ¿What do I do? There are two paths from here: @@ -66,6 +164,8 @@ Refactor the functions involved in the functionality to make them not rely directly with editor and other higher level componets, and test the lower level ones. +An example of this can be seen in commands + ### Use aditional tools to test a running flow session Use additional tools to invoke the built editor and send keys to From a9764039db4dc9810f2007da7947133218998eef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20T=C3=A1mara?= Date: Wed, 29 Oct 2025 08:54:19 -0500 Subject: [PATCH 05/10] feat: add edit and zig icons --- assets/css/webfont.css | 6 ++++++ assets/fonts/SymbolsNerdFontMono-Regular.ttf | Bin 2772 -> 3152 bytes contrib/symbolnerdfontmonolist.txt | 2 ++ 3 files changed, 8 insertions(+) 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 c5622a1bf8f921e9d78188d4023a2dc246b5a227..e45ec1d0bc1eee1c098b42784bdd678fbaff1231 100644 GIT binary patch delta 716 zcmZXSUr1AN6vxlGce}fH$=3DG`DdVBr<)ZzymxIyZd3|su;D{(QIXDN+nUpXBI`+r zAc7tWeMzK9B20QH_EJzG72$)B4>2-&vWLvl{$NnK-E}7P)bIE3JD=}4oO6D^-+5E9 zRCUcdE^GooUo;g-zj!q#0~n7H4@SpE>!DLG63-LsVv&(_u?Q?cSr;)M8@zBXx_`<@ z_9EfM_(0@rUAF8#fN+U4Pn-l(Lcc-0MBErpjb`{yFire~*fKaAjTj%4ody+zbV*1> zGHG}%DHPB{Tt5^^4OCC5ZPdU^0PIf>kBk;|5Tgc~A1>@+6Hj^I%wPlwY~=T%%*q1F zxQk)i?4rurQ59uL743!`vz24|wZh#(TDQ9}jli7z^N5N62#)1v3}(Hq!7ed;y?$;KNPG%ai8|*qWu7h6fnc+5vAW%sM1gNN^!Hkt&kK2h(&Wv7< z7oCzvsY9#9fSf_kIUQb!L|L&~IJ?}yRfra=Dl4A7qT8cbiA+dxD-!#Wo2x!zOWr$g zv*j{$!?DKl_;d zqC2$hrx^b}remU+ck=+n-xSw7(Z}C9a)PXK*hw?RtX^6Dy7qp3X8q2$&hPb`0!qNt7PPs zRB$|G0Gh=S0^|$iSx>jBxu3>-Wlf!xH30*14~MnJ>f0Qm}eiMgqgvy2Ua4)9=L zU`#5=FE07d!jKMhz?zLGw3#<2vbTUIV*~&UBUms1 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 From 6182577f7effb3a9d347c8fc6a8c4add999e6bcf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20T=C3=A1mara?= Date: Wed, 29 Oct 2025 08:55:24 -0500 Subject: [PATCH 06/10] Remove next and prev navigation and use nerd font icons --- layouts/tutorial.shtml | 34 +++++++++------------------------- 1 file changed, 9 insertions(+), 25 deletions(-) diff --git a/layouts/tutorial.shtml b/layouts/tutorial.shtml index bd933c0..89fc8c2 100644 --- a/layouts/tutorial.shtml +++ b/layouts/tutorial.shtml @@ -5,34 +5,18 @@

-
-

- ← - - ; - ; - - - - Code - Code - → - → -

-
-
From 0b1d2b5f32ba67dace30c7c30289c63f80733479 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20T=C3=A1mara?= Date: Wed, 29 Oct 2025 10:12:13 -0500 Subject: [PATCH 07/10] Changed label for editing a page --- layouts/tutorial.shtml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/layouts/tutorial.shtml b/layouts/tutorial.shtml index 89fc8c2..e6ee2ce 100644 --- a/layouts/tutorial.shtml +++ b/layouts/tutorial.shtml @@ -13,10 +13,10 @@ code code - fix + edit - fix + edit From bea9c78e8e42898470752858e9aafc794588828d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20T=C3=A1mara?= Date: Wed, 29 Oct 2025 10:12:49 -0500 Subject: [PATCH 08/10] Update links between developer docs --- content/docs/architecture.smd | 12 ++++++------ content/docs/contributing.smd | 15 +++++---------- content/docs/testing.smd | 11 +++++++---- 3 files changed, 18 insertions(+), 20 deletions(-) diff --git a/content/docs/architecture.smd b/content/docs/architecture.smd index 8d2f3a1..16dbcf1 100644 --- a/content/docs/architecture.smd +++ b/content/docs/architecture.smd @@ -6,12 +6,6 @@ .draft = false, .custom = { .githubedit = "/docs/architecture.smd", - .prevurl = "https://github.com/neurocyte/flow", - .prevtext = "Code", - .nexturl = "/docs/contributing", - .nexttext = "Contributing", - .topurl = "/docs/", - .toptext = "Docs", } --- Head to: [Contribution guidelines](/docs/contributing). @@ -104,3 +98,9 @@ support to use the system clipboard, copying and pasting to/from it. 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`. + +## 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 5bc2b45..e32cd98 100644 --- a/content/docs/contributing.smd +++ b/content/docs/contributing.smd @@ -6,12 +6,6 @@ .draft = false, .custom = { .githubedit = "/docs/contributing.smd", - .nexturl = "/docs/testing", - .nexttext = "Testing", - .topurl = "/docs/", - .toptext = "Docs", - .prevurl = "/docs/architecture", - .prevtext = "Architecture", } --- @@ -105,8 +99,9 @@ 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. +## Next steps -[Discord](https://discord.com/invite/4wvteUPphx) and -[Github issues](https://github.com/neurocyte/flow/issues) are the -main channels to do so. +* [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 index f76ca41..1444870 100644 --- a/content/docs/testing.smd +++ b/content/docs/testing.smd @@ -6,10 +6,6 @@ .draft = false, .custom = { .githubedit = "/docs/testing.md", - .prevurl = "/docs/contributing", - .prevtext = "Contributing", - .topurl = "/docs/architecture", - .toptext = "Architecture", .codepath ="test", }, --- @@ -174,3 +170,10 @@ 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). + + +## Next steps + +* [How to contribute](/docs/contributing) +* [User Documentation](/docs) +* [Other Flow topics](/docs/architecture) \ No newline at end of file From 6b5bf768f2afb01959084785cb092ba7f16eab4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20T=C3=A1mara?= Date: Wed, 29 Oct 2025 10:25:14 -0500 Subject: [PATCH 09/10] Add instructions on custom frontmatter --- README.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) 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/) 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 10/10] 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)