diff --git a/conf.py b/conf.py index 5c983664e52..054d1e88b34 100644 --- a/conf.py +++ b/conf.py @@ -25,6 +25,8 @@ import os from hashlib import md5 from sphinx.roles import MenuSelection +from docutils import nodes +from docutils.parsers.rst import roles project = 'QGIS Documentation' copyright = '2002-now, QGIS project' @@ -161,10 +163,6 @@ 'isLtr': False, } -# Add custom CSS when a top bar is needed to be shown (for testing or outdated versions) -if html_context['isTesting'] or html_context['outdated']: - html_css_files = ['css/qgis_topbar.css'] - # Add custom tags to allow display of text based on the branch status if html_context['isTesting']: tags.add('testing') @@ -255,6 +253,23 @@ def calculate_tx_slug(filepath): # A list of warning codes to suppress arbitrary warning messages. suppress_warnings = ["config.cache"] +# -- Custom text roles for colored sockets --------------------------------- + +def make_colored_role(color_name): + def role(name, rawtext, text, lineno, inliner, options={}, content=[]): + node = nodes.inline(text, text) + node['classes'].append(color_name) + return [node], [] + return role + +colors = [ + "red", "blue", "green", "kaki", "turquoise", + "purple", "slate", "darkgray", "midgray" +] + +for c in colors: + roles.register_local_role(c, make_colored_role(c)) + # -- Options for LaTeX output -------------------------------------------------- latex_engine = 'xelatex' @@ -327,7 +342,22 @@ def calculate_tx_slug(filepath): \\newunicodechar{\u25BA}{$\u25BA$} \\newunicodechar{′}{\\ensuremath{^{\\prime}}} \\newunicodechar{″}{\\ensuremath{^{\\prime\\prime}}} - \\newunicodechar{​}{ }''', + \\newunicodechar{​}{ }''' + + + # Add specific text roles with color display + ''' + \\usepackage{xcolor} + \\newcommand{\\DUrolered}[1]{{\\color[HTML]{FF0000} #1}} + \\newcommand{\\DUroleblue}[1]{{\\color[HTML]{229DD6} #1}} + \\newcommand{\\DUrolegreen}[1]{{\\color[HTML]{33C91C} #1}} + \\newcommand{\\DUrolekaki}[1]{{\\color[HTML]{B4B400} #1}} + \\newcommand{\\DUroleturquoise}[1]{{\\color[HTML]{00B4B4} #1}} + \\newcommand{\\DUrolepurple}[1]{{\\color[HTML]{8044C9} #1}} + \\newcommand{\\DUroleslate}[1]{{\\color[HTML]{6464FF} #1}} + \\newcommand{\\DUroledarkgray}[1]{{\\color[HTML]{505050} #1}} + \\newcommand{\\DUrolemidgray}[1]{{\\color[HTML]{808080} #1}} + ''', # Latex figure float alignment # use ‘H’ to disable floating, and position the figures strictly in the order they appear in the source diff --git a/docs/user_manual/processing/img/models_model.png b/docs/user_manual/processing/img/models_model.png index f99bc2a4d85..59db7cbd44a 100644 Binary files a/docs/user_manual/processing/img/models_model.png and b/docs/user_manual/processing/img/models_model.png differ diff --git a/docs/user_manual/processing/modeler.rst b/docs/user_manual/processing/modeler.rst index 4d9d89a2ab8..b4966d49e06 100644 --- a/docs/user_manual/processing/modeler.rst +++ b/docs/user_manual/processing/modeler.rst @@ -198,6 +198,12 @@ View menu - - - Displays comments associated to every algorithm or input in the model designer + * - |checkbox| :guilabel:`Show Feature Count` + - + - + - Displays the number of features on the links between algorithms, + for vector layer connections. The model must be run at least once + to populate the feature counts. * - |unchecked| :guilabel:`Enable Snapping` - - @@ -436,6 +442,57 @@ A visual edge follows the cursor and completes the connection when released. To remove a connection, drag the edge away from the input socket. The algorithm dialogs update automatically to reflect changes made using the drag-and-drop interface. +In the model designer, input and output sockets are color-coded to indicate +the type of data they accept or produce. The same color coding applies to +rubber bands and parameter bullets on the canvas. +The color is a visual aid only; compatibility between sockets is determined +by the parameter type. + +The following table describes the meaning of each socket color. + +.. list-table:: + :header-rows: 1 + :widths: 25 35 40 + + * - Socket color + - Data type category + - Description + * - :green:`Green` + - Boolean + - ``True`` / ``False`` values. + * - :purple:`Purple` + - Enumerations + - Predefined selectable values (enum parameters). The selected value is + shown using its descriptive label rather than its numeric index. + * - :blue:`Blue` + - Numerical types + - Numbers, matrices, vectors, distances, durations, and other numeric values. + * - :slate:`Slate blue` + - Textual types + - Strings, dates, coordinate reference systems (CRS), HTML content, and other text-based values. + * - :kaki:`Kaki` + - Vector and geometry types + - Vector geometries and vector layers, including meshes, point clouds, extents, vector tiles, and any object containing geometry. + * - :turquoise:`Turquoise` + - Raster types + - Raster images and raster layers. + * - :darkgray:`Dark gray` + - File system types + - File and directory paths. + * - :midgray:`Mid gray` + - Other types + - Parameters that do not fit into the above categories. + +Sockets can only be connected when their data types are compatible. +Parameter bullets use the same color coding as sockets: a bullet is outlined +when the parameter holds its default value, and filled when a non-default value +is set or a parameter box is connected. The label of each parameter is followed +by its current value, which updates immediately as values are changed or +parameter boxes are connected. + +When a parameter box is unfolded, its output section also shows the data type +and current value being passed downstream. + .. _figure_model_model: .. figure:: img/models_model.png @@ -443,6 +500,12 @@ The algorithm dialogs update automatically to reflect changes made using the dra A complete model +The model designer can display the number of features flowing through +the connections between algorithms. Feature counts are shown on the links +between algorithm inputs and outputs, and apply to vector layers only. +The model must be run at least once before feature counts can be displayed. +Feature counts can be toggled on or off via :menuselection:`View --> Show Feature Count`. + With the :menuselection:`Edit --> Add Group Box` tool, you can add a draggable *box* to the canvas. This feature is very useful in big models to group related elements in the modeler canvas and to keep the diff --git a/themes/rtd_qgis/static/css/qgis_docs.css b/themes/rtd_qgis/static/css/qgis_docs.css index 7e221fbf315..3d4a289bbcf 100644 --- a/themes/rtd_qgis/static/css/qgis_docs.css +++ b/themes/rtd_qgis/static/css/qgis_docs.css @@ -3,47 +3,53 @@ /* Customize for QGIS Documentation*/ .rst-content .guilabel { - background:#7fbbe3 + background: #7fbbe3 } /* adds scrollbar to side navigator and keep showing the top title block */ .wy-side-nav-search { - margin-bottom: 0; + margin-bottom: 0; } + .wy-side-scroll { - width: auto; - overflow-y: hidden; - display: flex; - flex-direction: column; + width: auto; + overflow-y: hidden; + display: flex; + flex-direction: column; } + .wy-menu.wy-menu-vertical { - overflow-y: auto; + overflow-y: auto; } /*rtd theme does not render menuselection, so let's apply guilabel settings to it*/ .rst-content .menuselection { - background:#7fbbe3; - font-size: 80%; - border:1px solid #7fbbe3; - font-weight:700; - border-radius:4px; - padding:2.4px 6px; - margin:auto 2px + background: #7fbbe3; + font-size: 80%; + border: 1px solid #7fbbe3; + font-weight: 700; + border-radius: 4px; + padding: 2.4px 6px; + margin: auto 2px } + /*keyboard text are by default rendered bigger*/ .rst-content .kbd { - font-size: 90% + font-size: 90% } + .outdated { /* only to be visible for outdated releases*/ background: #ffbaba; color: #6a0e0e; } + .isTesting { /* only to be visible in testing*/ background: #f3fbfb; color: black; } + .outdated, .isTesting { /* top banner for testing and outdated docs*/ @@ -59,7 +65,7 @@ /* Widen space for the documentation content*/ .wy-nav-content { - max-width: 1260px; + max-width: 1260px; } /* Avoid images being too big on bigger screen*/ @@ -73,15 +79,15 @@ from https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html */ @media screen and (min-width: 767px) { - .wy-table-responsive table td { - /* !important prevents the common CSS stylesheets from overriding + .wy-table-responsive table td { + /* !important prevents the common CSS stylesheets from overriding this as on RTD they are loaded after this stylesheet */ - white-space: normal !important; - } + white-space: normal !important; + } - .wy-table-responsive { - overflow: auto !important; - } + .wy-table-responsive { + overflow: auto !important; + } } .toc-columns ul { @@ -101,3 +107,43 @@ from https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html */ display: none; } } + + +/* Add specific text roles with color display, allowing to write e.g., :blue:`Blue socket` */ +@import url("default.css"); + +.red { + color: #FF0000; +} + +.blue { + color: #229DD6; +} + +.green { + color: #33C91C; +} + +.kaki { + color: #B4B400; +} + +.turquoise { + color: #00B4B4; +} + +.purple { + color: #8044C9; +} + +.slate { + color: #6464FF; +} + +.darkgray { + color: #505050; +} + +.midgray { + color: #808080; +} \ No newline at end of file