Add an architecture documentation

CONTRIBUTING.md

@@ -28,6 +28,8 @@ To get involved more deeply, please take a look at the [roadmaps](doc/dev/ROADMA
 
 It is also recommended to reach out on [Discord](https://discord.f3d.app) to simplify communication, but it is not required.
 
+You may also want to understand the overall [architecture](doc/dev/ARCHITECTURE.md) of the F3D project.
+
 You can then fix the issue or implement the feature on your side and contribute it to the F3D repository by following the workflow described below.
 
 Of course, if you are already using F3D and want to improve it for your specific needs, because you want a feature or found a bug,

_config.yml

@@ -267,53 +267,61 @@ defaults:
       parent: Developer Documentation
       nav_order: 4
 
+  -
+    scope:
+      path: "doc/dev/ARCHITECTURE.md"
+    values:
+      title: Architecture
+      parent: Developer Documentation
+      nav_order: 5
+
   -
     scope:
       path: "doc/dev/CODING_STYLE.md"
     values:
       title: Coding style
       parent: Developer Documentation
-      nav_order: 5
+      nav_order: 6
 
   -
     scope:
       path: "doc/dev/ROADMAPS_AND_RELEASES.md"
     values:
       title: Roadmaps and release cycle
       parent: Developer Documentation
-      nav_order: 6
+      nav_order: 7
 
   -
     scope:
       path: "doc/dev/GOVERNANCE.md"
     values:
       title: Governance
       parent: Developer Documentation
-      nav_order: 7
+      nav_order: 8
 
   -
     scope:
       path: "doc/dev/MAINTAINERS.md"
     values:
       title: Maintainers
       parent: Developer Documentation
-      nav_order: 8
+      nav_order: 9
 
   -
     scope:
       path: "CODE_OF_CONDUCT.md"
     values:
       title: Code of conduct
       parent: Developer Documentation
-      nav_order: 9
+      nav_order: 10
 
   -
     scope:
       path: "doc/dev/BUILD_WASM.md"
     values:
       title: Build (WebAssembly)
       parent: Developer Documentation
-      nav_order: 10
+      nav_order: 11
 
 # Licenses doc
 # _licenses.md uses front matter      

doc/dev/ARCHITECTURE.md

@@ -0,0 +1,68 @@
+# F3D Architecture
+
+F3D is structured in different parts, interacting with each others and with F3D dependencies.
+This architecture is reflected by the directories organisation.
+
+- **application**: the code of the F3D application itself, see below
+- cmake: cmake macros and functions, used by the CMake build system
+- doc: this very documentation
+- examples: examples usage of the libf3d and plugin framework in python and C++
+- external: dependencies that are included directly in the code
+- java: [java bindings](../libf3d/LANGUAGE_BINDINGS.md#java-experimental) and associated tests.
+- **library**: the [libf3d](../libf3d/README_LIBF3D.md) itself, see below
+- **plugins**: all the [plugins](../libf3d/PLUGINS.md) providing different readers, see below
+- python: [python bindings](../libf3d/LANGUAGE_BINDINGS.md#python) and tests
+- resources: all non code, non doc, like icon, configs and such
+- testing: all testing related resources, does not contain the test themselves
+- **vtkext**: extensions to VTK and related tests, see below
+- webassembly: [webassembly/javascript bindings](../libf3d/LANGUAGE_BINDINGS.md#javascript-experimental) and [F3DWeb](https://f3d.app/web/) application code
+- winshellext: shell extension for Windows, provide [thumbnails for Windows](../user/DESKTOP_INTEGRATION.md#windows)
+
+Here is diagram explaining how some of these parts interact together:
+
+<img src="https://media.githubusercontent.com/media/f3d-app/f3d-media/c43c1367a2aac4c9a3bdd478bdac3ffefe82750e/media/archi.png" width="700">
+
+## vtkext
+
+`vtkext` contains two [VTK modules](https://docs.vtk.org/en/latest/api/cmake/ModuleSystem.html) that are used extensively in the libf3d. The public one is used in the plugins.
+
+`public` is a VTK module that contains classes and utilities that can be installed as part of the `plugin_sdk` and used by plugins, including externals plugins. `vtkF3DImporter` is a class
+that is specifically made for plugin developers to inherit their importers from. The documentation of this module can be found [here](https://f3d.app/doc/libf3d/vtkext_doxygen/).
+
+`private` is a VTK module that contains many classes and utilities used by the libf3d to provide all features of F3D, especially the rendering, interactions and UI.
+A notable class is `vtkF3DRenderer` that is responsible to actually add the different actors in the 3D scene.
+
+Each of these modules also contains [tests](TESTING.md#vtkextensions-layer) in the `Testing` directory.
+
+## plugins
+
+`plugins` contains [libf3d plugins](../libf3d/PLUGINS.md) that are provided by default in the F3D packages. Each of these plugins correspond to a specific dependency and are named accordingly. Each of these plugins provide access to specific readers for specific formats. Without plugins, F3D and the libf3d would not be able to open any file. These plugins can be loaded statically or dynamically, which makes the dependencies truly optional if needed.
+
+## library
+
+`library` contains the code of the libf3d. It is a C++ library with a very limited API surface and larger, private, implementation.
+Most classes in the libf3d are split in two. A public part that contains mostly the public API, and a private part, suffixed "\_impl", that implements that public API
+and also contains hidden methods used to communicate between classes, especially in regards to VTK symbols.
+
+Logically, it is structured in 3 parts, `public` which contains the public API header files and are all installed, `private` which contains the implementation classes headers files and `src` that contains the source files of all the classes, public and private.
+
+There is also a dedicated `testing` directory which contains the [unit and functional testing](TESTING.md#library-layer) of the libf3d.
+
+It also contains the `options.json` file, which is the file used to generate all [options](../libf3d/OPTIONS.md) code.
+
+## application
+
+`application` contains the code of the F3D application itself. It relies of course on the libf3d to implement all the applicative logic.
+The most important class in the `F3DStarter` which contains most of the top logic on the application. `F3DOptionsTools` is also notable as it handles most of
+the command line options logic.
+
+There is also a dedicated `testing` directory which contains all of the [applicative testing](TESTING.md#application-layer) of the F3D application as well as many functional testing of the libf3d.
+
+## Other f3d-app repositories
+
+Although almost everything is contained in the [f3d-app/f3d](https://github.com/f3d-app/f3d) repository, other repositories in the [f3d-app](https://github.com/f3d-app) organisation are handling certains specific tasks in the F3D ecosystem.
+
+- The [f3d-superbuild](https://github.com/f3d-app/f3d-superbuild) handles the packaging and the creation of the binaries provided in the [releases page](https://github.com/f3d-app/f3d/releases).
+- [f3d-media](https://github.com/f3d-app/f3d-media) backups all images and video used in this documentation
+- A collection of actions: [sccache-setup](https://github.com/f3d-app/sccache-setup-action), [lfs-data-cache](https://github.com/f3d-app/lfs-data-cache-action) and [install-mesa-windows](https://github.com/f3d-app/install-mesa-windows-action) used by the CI of F3D
+- A collection of [docker files](https://github.com/f3d-app/f3d-docker-images) used for generating docker images used by the CI of F3D

doc/dev/README_DEV.md

@@ -5,6 +5,7 @@
 - [How to test F3D.](TESTING.md)
 - [How to contribute to F3D.](../../CONTRIBUTING.md)
 - [How to Generate coverage and sanitizer report.](GENERATE.md)
+- [Overview of the architecture of F3D.](ARCHITECTURE.md)
 - [Coding Style.](CODING_STYLE.md)
 - [Roadmaps and release cycle.](ROADMAPS_AND_RELEASES.md)
 - [Governance.](GOVERNANCE.md)

doc/libf3d/PLUGINS.md

@@ -10,7 +10,7 @@ You will then be able to call `find_package(f3d REQUIRED COMPONENTS pluginsdk)`
 
 You can take a look at the example in the [examples/plugin](https://github.com/f3d-app/f3d/tree/master/examples/plugins) directory or at the official [plugins](https://github.com/f3d-app/f3d/tree/master/plugins).
 
-The first thing (and most difficult part) you have to do is creating a VTK reader (or a VTK importer if you want to support a full scene with materials, lights and cameras), and wrap it into a VTK module. You can create several readers in the same VTK module if you need to support several file formats in a single plugin.
+The first thing (and most difficult part) you have to do is creating a VTK reader (or a VTK importer if you want to support a full scene with materials, lights and cameras), and wrap it into a VTK module. You can create several readers/importers in the same VTK module if you need to support several file formats in a single plugin.
 
 Then, declare the reader(s) and the plugin using the CMake macros:
 
@@ -21,11 +21,20 @@ f3d_plugin_declare_reader(
   NAME "ReaderName"
   EXTENSIONS "myext"                # set the extensions the reader can support
   MIMETYPES "application/vnd.myext" # set the mimetypes the reader can support
-  VTK_READER ${vtk_classname}       # set the name of the VTK class you have created
-  DESCRIPTION "Reader description"  # set the description of the reader
+  VTK_READER ${vtk_classname}       # set the name of the VTK reader class you have created
+  FORMAT_DESCRIPTION "description"  # set the proper name of the file format
   EXCLUDE_FROM_THUMBNAILER          # add this flag if you don't want thumbnail generation for this reader
 )
 
+f3d_plugin_declare_reader(
+  NAME "ReaderNameWithScene"
+  EXTENSIONS "myext2"                # set the extensions the reader can support
+  MIMETYPES "application/vnd.myext2" # set the mimetypes the reader can support
+  VTK_IMPORTER ${vtk_classname}      # set the name of the VTK importer class you have created
+  FORMAT_DESCRIPTION "description"   # set the proper name of the file format
+  CUSTOM_CODE "file.inl"             # set this to add a custom code when instancing your class
+)
+
 # More f3d_plugin_declare_reader calls are possible
 
 f3d_plugin_build(