Docs: shuffle the modules README

src/modules/README.md

@@ -8,27 +8,28 @@ Each Calamares module lives in its own directory.
 
 All modules are installed in `$DESTDIR/lib/calamares/modules`.
 
-# Module types
-
-There are two types of Calamares module:
+There are two **types** of Calamares module:
 * viewmodule, for user-visible modules. These may be in C++, or PythonQt.
 * jobmodule, for not-user-visible modules. These may be done in C++,
   Python, or as external processes.
 
-# Module interfaces
+A viewmodule exposes a UI to the user. The PythonQt-based modules
+are considered experimental (and as of march 2019 may be on the
+way out again as never-used-much and PythonQt is not packaged
+on Debian anymore).
 
-There are three (four) interfaces for Calamares modules:
+There are three (four) **interfaces** for Calamares modules:
 * qtplugin (viewmodules, jobmodules),
 * python (jobmodules only),
 * pythonqt (viewmodules, jobmodules, optional),
 * process (jobmodules only).
 
-# Module directory
+## Module directory
 
 Each Calamares module lives in its own directory. The contents
 of the directory depend on the interface and type of the module.
 
-## Module descriptor
+### Module descriptor
 
 A Calamares module must have a *module descriptor file*, named
 `module.desc`. For C++ (qtplugin) modules using CMake as a build-
@@ -55,7 +56,28 @@ Module descriptors **may** have the following keys:
 - *emergency* (a boolean value, set to true to mark the module
   as an emergency module)
 
-## Module-specific configuration
+### Emergency Modules
+
+Only C++ modules and job modules may be emergency modules. If, during an
+*exec* step in the sequence, a module fails, installation as a whole fails
+and the install is aborted. If there are emergency modules in the **same**
+exec block, those will be executed before the installation is aborted.
+Non-emergency modules are not executed.
+
+If an emergency-module fails while processing emergency-modules for
+another failed module, that failure is ignored and emergency-module
+processing continues.
+
+Use the EMERGENCY keyword in the CMake description of a C++ module
+to generate a suitable `module.desc`.
+
+A module that is marked as an emergency module in its module.desc
+must **also** set the *emergency* key to *true* in its configuration file
+(see below). If it does not, the module is not considered to be an emergency
+module after all (this is so that you can have modules that have several
+instances, only some of which are actually needed for emergencies).
+
+### Module-specific configuration
 
 A Calamares module **may** read a module configuration file,
 named `<modulename>.conf`. If such a file is present in the
@@ -74,6 +96,8 @@ All sample module configuration files are installed in
 files with the same name placed manually (or by the packager)
 in `/etc/calamares/modules`.
 
+
+
 ## C++ modules
 
 Currently the recommended way to write a module which exposes one or more
@@ -85,6 +109,8 @@ To add a Qt plugin module, put it in a subdirectory and make sure it has
 a `CMakeLists.txt` with a `calamares_add_plugin` call. It will be picked
 up automatically by our CMake magic. The `module.desc` file is optional.
 
+
+
 ## Python modules
 
 Modules may use one of the python interfaces, which may be present
@@ -119,6 +145,17 @@ function `run()` as entry point. The function `run()` must return `None` if
 everything went well, or a tuple `(str,str)` with an error message and
 description if something went wrong.
 
+### Python API
+
+**TODO:** this needs documentation
+
+
+
+## PythonQt modules
+
+The PythonQt modules are considered experimental and may be removed again
+due to low uptake. Their documentation is also almost completely lacking.
+
 ### PythonQt Jobmodule
 
 A PythonQt jobmodule implements the experimental Job interface by defining
@@ -129,33 +166,18 @@ a subclass of something.
 A PythonQt viewmodule implements the experimental View interface by defining
 a subclass of something.
 
+### Python API
+
+**TODO:** this needs documentation
+
+
+
 ## Process jobmodules
 
-A process jobmodule runs a (single) command. The interface is "process",
-while the module type must be "job" or "jobmodule".
+A process jobmodule runs a (single) command. The interface is *process*,
+while the module type must be *job* or *jobmodule*.
 
-The key *command* should have a string as value, which is passed to the
-shell -- remember to quote it properly. It is generally recommended to use
-a *shellprocess* job module instead (less configuration, easier to have
-multiple instances).
-
-## Emergency Modules
-
-Only C++ modules and job modules may be emergency modules. If, during an
-*exec* step in the sequence, a module fails, installation as a whole fails
-and the install is aborted. If there are emergency modules in the **same**
-exec block, those will be executed before the installation is aborted.
-Non-emergency modules are not executed.
-
-If an emergency-module fails while processing emergency-modules for
-another failed module, that failure is ignored and emergency-module
-processing continues.
-
-Use the EMERGENCY keyword in the CMake description of a C++ module
-to generate a suitable `module.desc`.
-
-A module that is marked as an emergency module in its module.desc
-must **also** set the *emergency* key to *true* in its configuration file.
-If it does not, the module is not considered to be an emergency module
-after all (this is so that you can have modules that have several
-instances, only some of which are actually needed for emergencies.
+The module-descriptor key *command* should have a string as value, which is
+passed to the shell -- remember to quote it properly. It is generally
+recommended to use a *shellprocess* job module instead (less configuration,
+easier to have multiple instances).