Separate FLUID user documentation, screen shot automation #936

MatthiasWM · 2024-03-17T13:30:00Z

Incrementally adding user documentation for FLUID. Non-widget node types are don at this point.

I am tying to user automatically generated screen shots to document FLUID features visually. To not pollute the repo with hundreds of small png's, screen shots are created by FLUID with a new command line option --autodoc path.

I am not great at writing documentation, neither in English nor in German, so the handbook will be more of a pice by piece description of what elements in the user interface do. But that's probably still better than no docs at all. If all goes well, I will move the FLUID parts of the FLTK docs over here.

For now, this is more of a pull announcement than a pull request. I am always happy to hear recommendations and fixes.

MatthiasWM · 2024-03-18T18:23:49Z

State of the FLUID Docs: http://elektriktrick.com/fluid/index.html

Albrecht-S · 2024-03-19T13:58:12Z

Great stuff for users and developers like me. I can't tell much about the contents (I don't know fluid well) and I didn't have the time for full proof reading. Would it make sense to check text and typos at this time, or are you still developing (and/or rewriting) substantially?

MatthiasWM · 2024-03-19T15:52:51Z

@Albrecht-S Thanks for taking quick look. As a next iteration, I will merge the existing documentation with what I wrote here and create a hopefully helpful and complete handbook. I will post here when that is done. That's probably the best time for proof reading.

If devs then agree, I will remove the current FLUID docks from the FLTK docs and just leave a reference to advertise the existence of FLUID there. After that, the pull request can be applied in the hopes that 1.4.0 gets some shiny new detailed docs for FLUID.

I purposely do not include inner workings or a class reference. Not everything is documented anyway, and 1.5 will bring a new constant naming scheme.

MatthiasWM · 2024-03-26T19:18:59Z

Ok, so I am 98% done. I merged the original docs with the new docs and fixed what was changed in FLUID. I still want to add two short tutorials to bring some points across. Other than that, happy to hear comments.

Also, we need to decide on how to reference the new docs from the FLTK docs, and If/where we want to put them on the fltk.org web page.

Refreshed http://elektriktrick.com/fluid/index.html .

Albrecht-S · 2024-04-14T13:21:20Z

.github/workflows/build_fluid_docs.yml

+        sudo apt-get install -y doxygen=1.10.0
+        sudo apt-get install texlive-latex-base
+        sudo apt-get install texlive-fonts-recommended
+        sudo apt-get install texlive-latex-extra


@MatthiasWM Instead of all these texlive-* packages installing doxygen-latex should do it. This should also imply doxygen but I don't know if doxygen=1.10.0 works (?)

Nope, Ubuntu is at 1.9.2. 1.10.0 does not work :-(

Albrecht-S · 2024-04-14T13:32:01Z

fluid/documentation/CMakeLists.txt

+
+  add_custom_target(fluid_docs
+    COMMAND echo fluid::fluid -scheme gtk+ --autodoc ${CMAKE_CURRENT_BINARY_DIR}/src/
+    COMMAND fluid::fluid -scheme gtk+ --autodoc ${CMAKE_CURRENT_BINARY_DIR}/src/


s/fluid::fluid/fltk::fluid/ ???

LOL, yes. Sorry, I will generate a bunch of commits until the workflow is well.

Sorry, I will generate a bunch of commits until the workflow is well.

That's what forks are good for. ;-)

MatthiasWM · 2024-04-14T19:04:15Z

PDF no longer shows front logo

Albrecht-S · 2024-04-14T21:41:26Z

fluid/documentation/src/page_edit_window.dox

+ To move or resize a widget, it must be selected first by clicking on it.
+ Multiple widgets can be selected by holding down the Shift key when clicking
+ on them, or by dragging a selection box around widgets. Widgets can also be
+ selected in the widget browser the main window. Shift-click will select a


in the widget browser the main window

should read: "in the widget browser {in|of} the main window"

Albrecht-S · 2024-04-14T21:44:11Z

fluid/documentation/src/page_edit_window.dox

-   may not follow changes in the grid widgets. It's best to first complete the
-   grid, and the add children to the grid cells later, size them correctly, and
+   may not follow changes in the grid widgets. It's best to complete the grid
+   first, then add children to the grid cells later, size them correctly, and
   the finally lay out the grid cell children.


IMHO either then finally or just finally rather than the finally

Albrecht-S · 2024-04-14T21:47:28Z

fluid/documentation/src/page_main_window.dox

-__Edit > Show or Hide Source Code (Shift+Alt+S)__: This button shows or hides
-the source code preview window. Any change to the layout or code in the layout
-editors can be previewed and verified immediately in the Code View window.
+__Edit > Show or Hide Source Code (Shift+Alt+S)__: Shows or hide


s/hide/hides/

Albrecht-S · 2024-04-14T21:48:57Z

fluid/documentation/src/page_widgetbin_panel.dox

@@ -20,15 +20,15 @@
 a dialog box will pop up, explaining what type of parent node is required.

 The Window and Widget Class icons can be dragged onto the desktop,
- creating a new window at the drop position.
+ creating a new window or widgetat the drop position.


Thank you!

After using Code View for a while, renamed all remaining references and files. Also renamed alignment_panel to settings_panel as its use changed dramatically.

Albrecht-S · 2024-04-17T17:47:34Z

Thanks very much, great job. I built the Fluid docs successfully on Linux, and installation worked as well as expected.

Awesome!

One really tiny issue though:

$ ninja html
[2/2] Generating HTML documentation
/git/fltk/master/documentation/src/forms.dox:21: warning: unable to resolve reference to 'fluid' for \ref command

MatthiasWM · 2024-04-17T18:25:46Z

Done.

MatthiasWM self-assigned this Mar 17, 2024

MatthiasWM added fluid Fast Light User Interface Designer (fluid) documentation Needs better documentation active Somebody is working on it labels Mar 17, 2024

MatthiasWM changed the title ~~InProgress: FLUID user documentation, screen shot automation~~ Separate FLUID user documentation, screen shot automation Apr 11, 2024

MatthiasWM marked this pull request as ready for review April 11, 2024 19:13

Albrecht-S reviewed Apr 14, 2024

View reviewed changes

MatthiasWM marked this pull request as draft April 14, 2024 19:03

Albrecht-S reviewed Apr 14, 2024

View reviewed changes

MatthiasWM added 12 commits April 17, 2024 17:27

Initial commit for automated user documentation screenshots

82b91be

FLUID skeleton documentation and CMake integration

1d34529

Add non-widget icons and text

73d9131

Finished docs for non-widget nodes.

6381532

Documentation for most of the Widget Panel.

2f4a131

Complete documentation of Widget Panel tabs

6f32d6a

Additional docs for the Widget Panel itself.

d5d549a

Add documentation for the Setting panel.

d263aa7

Add documentation for th Code View panel.

6763895

Add documentation for the widget bin.

fad4e64

Document main app window.

b708f02

Editor window documentation complete.

2eb776b

MatthiasWM added 23 commits April 17, 2024 17:27

Workflow tests

1df74ae

Workflow tests

4c7be78

Workflow tests

6fc7ffa

Workflow tests

bbcdcef

Daring a macOS build

798cfe6

Daring a macOS build

ab9bb9c

Back to Linux, trying to get X to run FLUID

86ee21b

Faking X

6847fcd

Faking X

6776626

Artifact

9c0e365

Fix spelling and grammar. Thanks to Albrecht for finding those.

b38a4e6

Sizes for all LATEX images

a992952

Sizes for all LATEX images (2)

c4a4268

Spacing

f4d3d06

Many fixes to errors and typos, found by Albrecht.

7f0a17c

Thank you!

Functions can only contain windows

7597149

Renamed Source View to Code View

373489e

After using Code View for a while, renamed all remaining references and files. Also renamed alignment_panel to settings_panel as its use changed dramatically.

Ensure images are generated

bf41f79

Minor fixes, title png shows

2b95f74

Remove FLUID docs references from FLTK docs

4689728

Reformatting all images to PNG to get an alpha channel

2b7d993

Image cropping

4918a25

Update actions for final releas

5e52386

MatthiasWM force-pushed the autodoc branch from c7aee22 to 5e52386 Compare April 17, 2024 15:39

MatthiasWM marked this pull request as ready for review April 17, 2024 15:46

MatthiasWM merged commit fd791a0 into fltk:master Apr 17, 2024

Albrecht-S added fixed The issue or PR was fixed. and removed active Somebody is working on it labels Apr 17, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Separate FLUID user documentation, screen shot automation #936

Separate FLUID user documentation, screen shot automation #936

MatthiasWM commented Mar 17, 2024

MatthiasWM commented Mar 18, 2024

Albrecht-S commented Mar 19, 2024

MatthiasWM commented Mar 19, 2024

MatthiasWM commented Mar 26, 2024

Albrecht-S Apr 14, 2024

MatthiasWM Apr 14, 2024

Albrecht-S Apr 14, 2024

MatthiasWM Apr 14, 2024

Albrecht-S Apr 14, 2024

MatthiasWM commented Apr 14, 2024

Albrecht-S Apr 14, 2024

Albrecht-S Apr 14, 2024

Albrecht-S Apr 14, 2024

Albrecht-S Apr 14, 2024

Albrecht-S commented Apr 17, 2024

MatthiasWM commented Apr 17, 2024

Separate FLUID user documentation, screen shot automation #936

Separate FLUID user documentation, screen shot automation #936

Conversation

MatthiasWM commented Mar 17, 2024

MatthiasWM commented Mar 18, 2024

Albrecht-S commented Mar 19, 2024

MatthiasWM commented Mar 19, 2024

MatthiasWM commented Mar 26, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MatthiasWM commented Apr 14, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Albrecht-S commented Apr 17, 2024

MatthiasWM commented Apr 17, 2024