Improve docs

README.md

@@ -1,10 +1,12 @@
 # Ansel
 
+[TOC]
+
+## What is it ?
+
 __Ansel__ is a better future for Darktable, designed from real-life use cases and solving actual problems,
 by the guy who did the scene-referred workflow and spent these past 4 years working full-time on Darktable.
 
-[Website](https://ansel.photos) (including docs, workflows, support, etc.)
-
 It is forked on Darktable 4.0, and is compatible with editing histories produced with Darktable 4.0 and earlier.
 It is not compatible with Darktable 4.2 and later and will not be, since 4.2 introduces irresponsible choices that
 will be the burden of those who commited them to maintain, and 4.4 will be even worse.
@@ -64,3 +66,4 @@ A couple of nice guys are trying their best to fix issues on Mac OS in a timely
 - [Project news](https://ansel.photos/en/news/)
 - [Community forum](https://community.ansel.photos/)
 - [Matrix chatrooms](https://app.element.io/#/room/#ansel:matrix.org)
+- [Support](https://ansel.photos/en/support/)

doc/Doxyfile

@@ -994,8 +994,14 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = ../src/external ./api ./doxygen-awesome-css ../build ../AppDir
-
+EXCLUDE                = ../src/external \
+                         ./api \
+                         ./doxygen-awesome-css \
+                         ../build \
+                         ../AppDir \
+                         ../src/tests/integration \
+                         ../README.md
+EXCLUDE
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
 # from the input.
@@ -1075,7 +1081,8 @@ IMAGE_PATH             =
 # need to set EXTENSION_MAPPING for the extension otherwise the files are not
 # properly processed by doxygen.
 
-INPUT_FILTER           =
+# Find //TODO and //FIXME and in code comments and treat them as the \todo command
+INPUT_FILTER           = "sed -Ee 's,(//|/\*).*(TODO|FIXME),\1! \\todo ,'"
 
 # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
 # basis. Doxygen will compare the file name with each pattern and apply the
@@ -2474,7 +2481,7 @@ DOT_NUM_THREADS        = 8
 # The default value is: fontname=Helvetica,fontsize=10.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_COMMON_ATTR        = "fontname=FreeSans,fontsize=10"
+DOT_COMMON_ATTR        = "fontname=FreeSans,fontsize=12"
 
 # DOT_EDGE_ATTR is concatenated with DOT_COMMON_ATTR. For elegant style you can
 # add 'arrowhead=open, arrowtail=open, arrowsize=0.5'. <a
@@ -2483,7 +2490,7 @@ DOT_COMMON_ATTR        = "fontname=FreeSans,fontsize=10"
 # The default value is: labelfontname=Helvetica,labelfontsize=10.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_EDGE_ATTR          = "labelfontname=FreeSans,labelfontsize=10"
+DOT_EDGE_ATTR          = "labelfontname=FreeSans,labelfontsize=12"
 
 # DOT_NODE_ATTR is concatenated with DOT_COMMON_ATTR. For view without boxes
 # around nodes set 'shape=plain' or 'shape=plaintext' <a

doc/compress-doc.sh

@@ -0,0 +1,3 @@
+#! /bin/bash
+cd api
+tar -czvf doc.tar.gz -C html .

doc/grouping.md

@@ -0,0 +1,36 @@
+# Image grouping feature
+
+[TOC]
+
+- remove image from group before removing/deleting it. [done]
+- add duplicates to the same group as the original image. [done]
+
+## 'G' off:
+
+- display all images. [done]
+- draw a border around all the images in the group when hovering over an image with the mouse. [done]
+- merge border of adjacent images. [done]
+- add config option whether border is to be painted or not. [done]
+- disable grouping accels (ctrl-g, ctrl-shift-g) so that people don't hide their images where they won't find them again without noticing. [done]
+
+## 'G' on:
+
+- only display a single image ("representative") from each group. [done]
+- show the 'G' in a corner of the thumbnail. [done]
+- expand the group temporarily when clicking the 'G'. [done]
+- when expanding a group while another group is already expanded, then also collapse the latter. [done]
+- show the 'G' for all images in a temporarily expanded group. [done]
+- draw the border around the images of the temporarily expanded group as if grouping was turned off, just in a different color. [done]
+- highlight the 'G' for the representative ... [done]
+- ... and when clicking the 'G' of another image in the expanded group, then this image shall become the representative. [done]
+- collapse the group when clicking the 'G' of the representative. [done]
+- ctrl/shift clicking the 'G' of a group selects all the images in the group. [done for expanded groups]
+- when a group is expanded and another image is selected, then this image can be joined to the group by ctrl-g. [done]
+- when multiple images are selected and no group is expanded, then ctrl-g will merge them into a new group. [done]
+- remove an image with ctrl-shift-g from a group. [done]
+- an image is the representative of the group iff id == group_id. [done]
+- expand the group after creating a duplicate and adding it. [done]
+
+## TODO:
+
+- rating/rejecting an image does the same to all images in the group iff the group is collapsed.

doc/index.md

@@ -0,0 +1,50 @@
+# Ansel Dev doc {#mainpage}
+
+[TOC]
+
+Welcome on the new [Ansel](https://ansel.photos) developer documentation. As it is brand-new, it is still in progress, but we are getting there.
+
+## Getting started
+
+### Getting the source code
+
+You will need Git:
+
+```bash
+git clone --recurse-submodules https://github.com/aurelienpierreeng/ansel.git
+```
+
+For cross-plateform building instructions, please refer to the [user doc](https://ansel.photos/en/doc/install/).
+
+### Getting in sync with the project
+
+Who are our users ? What are we trying to to ? How do we tackle problems ? How do we manage the project and its priorities ? [Read the contributor section](https://ansel.photos/en/contribute).
+
+### Find issues to tackle
+
+- [TODO list](todo.html) from code `//TODO` and `//FIXME` comments,
+- [Github issues](https://github.com/aurelienpierreeng/ansel/issues)
+
+## Scope and purpose of the present doc
+
+At this stage, the present documentation is mostly the API reference automatically built by Doxygen from the (few) docstrings found in the source code, in particular in `.h` header files. Those documented objects aim at being reusable, so a documentation makes them public.
+
+Dependencies and function calls graphs are also plotted for each object. These are useful to track bugs through the chain of callings without having to grep them in the code, in a less graphical way. They also show the shitshow inherited from upstream Darktable in terms of non-modular modules : you see how everything includes everything, so the spaghetti code becomes quite literally visible.
+
+As time will go, we will add real dev documentation, explaining how the core tasks are handled, based on what assumptions and covering what use cases. This should prevent re-implementing the same feature, sometimes 4 times or more, as was seen in Darktable since 2020.
+
+## Useful links
+
+## Useful links
+
+- [User documentation](https://ansel.photos/en/doc/), in particular:
+    - [Build and test on Linux](https://ansel.photos/en/doc/install/linux)
+    - [Build and test on Windows](https://ansel.photos/en/doc/install/linux)
+- [Contributing guidelines](https://ansel.photos/en/contribute/), in particular:
+    - [Project organization](https://ansel.photos/en/contribute/organization/)
+    - [Translating](https://ansel.photos/en/contribute/translating/)
+    - [Coding style](https://ansel.photos/en/contribute/coding-style/)
+- [Project news](https://ansel.photos/en/news/)
+- [Community forum](https://community.ansel.photos/)
+- [Matrix chatrooms](https://app.element.io/#/room/#ansel:matrix.org)
+- [Support](https://ansel.photos/en/support/)

doc/man/README.md

@@ -1,12 +1,13 @@
-Authors
-=======
+# Adding man pages
+
+## Authors
+
 
 To add a new man page just write it in .pod format and add it to the list at the top of `CMakeLists.txt`. Then rerun cmake. Make sure to add the `$Date$` and `$Release$` lines in the end of the file.
 
 When editing a man page make sure to update the `$Date$` and `$Release$`.
 
-Translators
-===========
+## Translators
 
 For translating man pages we use `po4a`.
 

doc/thumbnail_color_management.txt → doc/thumbnail_color_management.md

@@ -1,9 +1,13 @@
+# Thumbnails color management
+
+[TOC]
+
 to ease debugging the code will use DT_COLORSPACE_DISPLAY for images loaded without a color space mentioned in Exif or when explicitly exporting
 for the Display profile, while buffers get initialized as DT_COLORSPACE_NONE. if ever such a thumbnail gets encountered there is a bug
 (i.e., a code path where a thumbnail gets loaded without the color space being set).
 
 
-DRAWING/EXPOSE
+## DRAWING/EXPOSE
 
 - thumbnails are tagged as sRGB, AdobeRGB, Display or None
   None means that we got a code path which doesn't set the color space -> BUG
@@ -14,14 +18,14 @@ DRAWING/EXPOSE
         * put the resulting pixels on the screen
 
 
-WRITING CACHE TO DISK
+## WRITING CACHE TO DISK
 
 - thumbnails are tagged as sRGB, AdobeRGB, Display or None
 - mark sRGB and AdobeRGB in Exif
 - write JPEG
 
 
-REQUESTING MIPMAP
+## REQUESTING MIPMAP
 
 - reading thumbnail from disk cache
     - read JPEG
@@ -40,7 +44,7 @@ REQUESTING MIPMAP
 
 
 
-CONCLUSION
+## CONCLUSION
 
 when thumbnail color management is on:
 - we export new thumbnails as AdobeRGB
@@ -66,6 +70,6 @@ there are two cases where colors would be wrong:
   the cache when reading them)
 
 
-TODO
+## TODO
 what to do when loading a jpeg or other file to create a thumbnail and it's neither sRGB nor AdobeRGB but some random other format? Convert to
 AdobeRGB? dump pixels to screen and wait for the full pipe to run eventually to get color managed thumbnails?

src/control/jobs/import.md

@@ -1,4 +1,4 @@
-Roadmap
+# Import Roadmap
 
 ## Entrées
 
@@ -19,7 +19,7 @@ Roadmap
 ## Sorties
 
 - Cas avec copie -> fichier copié: `I/O`
-- Tous les cas -> nouvelles entrées en BdD : 
+- Tous les cas -> nouvelles entrées en BdD :
   - filmroll : ajouter l'image, `SQL`
   - image : ajouter nom, date import, EXIFs, tags etc., `SQL`
 - Dans tous les cas -> mettre à jour la vue en table lumineuse (en fonction du filmroll, tags, EXIFs, etc.), `GUI`
@@ -31,13 +31,13 @@ Roadmap
     - depuis `import.c:_selection_changed()`,
     - vers la structure `GList * ((dt_import_t *import)->files)`
 - [x] [GUI] Récupérer les `str` du chemin cible, patterns sous-dossier cible, et jobcode :
-    - depuis `gtk_label` 
+    - depuis `gtk_label`
     - vers `anselrc` config keys :
       - `session/base_directory_pattern`,
       - `session/sub_directory_pattern`,
       - `session/filename_pattern`,
       - `ui_last/import_jobcode`,
-- [X] [GUI] Récupérer le statut import simple vs import avec copie : 
+- [X] [GUI] Récupérer le statut import simple vs import avec copie :
     - depuis `gtk_checkbox`,
     - vers `anselrc` -> `ui_last/import_copy`
 - [X] [GUI] Récupérer la date du fichier :
@@ -75,4 +75,4 @@ Roadmap
         - oui : récupérer `film_id` du filmroll via ??
         - non : créer nouveau filmroll
     - [X] [I/O] Si copie, copier chemin origine -> chemin destination
-    - [ ] [DB] Mettre à jour l'entrée en BdB via `image_cache.c:dt_image_cache_write_release()`.
+    - [ ] [DB] Mettre à jour l'entrée en BdB via `image_cache.c:dt_image_cache_write_release()`.