The Cookbook is a wonderful way to help new QGIS developers to get started, but the QGIS Python API is complex and may seem confused for someone that is just starting. Would be good to have for the Processing Algorithms Tools (which a beginner developer would be used to) a documentation that explains its syntax and that shows a sample of code for its use.
This proposal will enrich the Processing Algorithms Documentation, the QGIS Python API and the Cookbook Cheat Sheet by adding links between them as well as missing information regarding to:
1) a Summary (e.g. found at Processing Algorithms Documentation on QGIS User Guide);
2) a Discussion/Usage (e.g. Processing Algorithms Documentation and Cook Book);
3) Syntax (e.g. QGIS Python API);
4) code example (e.g. Cheat Sheet and other parts of official documentation, other source of samples);
The aim is to have it for every processing algorithm tool, a path that may connect through all three QGIS official documentation (when necessary) to provide a smooth way to conduct the beginner from the cookbook to the QGIS Python API.
This proposal may embrace three of the eight examples of topics: Updating and improving documentation; Improving API documentation; Helping new QGIS devs to get started with improved developer documentation and utilities.
The Need For Syntax Along With Code Sample For Beginners
When I started to program for GIS uses (about 7 years ago) I got used to the way the documentation of ArcPy was (and still is), explaining what a particular function would do, explaining its syntax, arguments types and with a clear simple code sample of its use. With basic Python and knowing what I need to do, I could look at the documentation and do it. When I started to work with QGIS, I got lost with the difference between the ArcPy and the QGIS documentation. Something what took me few minutes to perform with ArcPy, now took me hours of research and attempts. Things may get even harder when English is not your first language. So if we have in the official documentation more samples of code along with its syntax (API), especially for every processing algorithm tool that the user is already used to, the experience for those that are looking to start or already have an intermediate knowledge of Python will be greater.
Proposed Solution
Add sample of code and links between documentation (QGIS Python/API, QGIS User Guide and PyQGIS Cookbook) providing a path to have: Summary, Discussion/Usage, Syntax (link to the QGIS Python API) and code example for every for every processing algorithms. The steps will be:
1 - Copy examples from https://webgeodatavore.github.io/pyqgis-samples/ into the official API documentation, by placing these examples into the class doxygen documentation. This also benefits the c++ documentation, and keeps the examples close to the code so that they can be easily updated and revised if the API changes.
2 - Improve the Processing algorithm documentation by adding Python code examples showing use of the algorithms
3 - Add links between documentation.
Example(s)
Here we have a brief comparison between the QGIS processing algorithm documentation and the ArcGIS Toolbox documentation:
Comparing the documentation the ArcGIS docs at https://desktop.arcgis.com/en/arcmap/10.3/tools/analysis-toolbox/clip.htm, an the equivalent in QGIS would be the Processing algorithm documentation (not the Python cookbook or the API docs). I.e. https://docs.qgis.org/3.10/en/docs/user_manual/processing_algs/gdal/rasterextraction.html?highlight=clip
We can notice a the difference in the presentation of the information to the reader (e.g. the QGIS ones don't include any Python code examples on how to run those algorithms).
The ArcPy documentation tends to have a pattern of Summary, Discussion/Usage, Syntax and code example. This pattern seems to make things clear to a beginner developer, specially the syntax and the samples of code.
QGIS Enhancement: Improving the Processing Algorithm Documentation and Python API
Date 2020/05/21
Author Romário Moraes Carvalho Neto (@romariocarvalhoneto)
Contact romariocarvalho@hotmail.com
maintainer @romariocarvalhoneto
Version QGIS 3.16
Summary
The Cookbook is a wonderful way to help new QGIS developers to get started, but the QGIS Python API is complex and may seem confused for someone that is just starting. Would be good to have for the Processing Algorithms Tools (which a beginner developer would be used to) a documentation that explains its syntax and that shows a sample of code for its use. This proposal will enrich the Processing Algorithms Documentation, the QGIS Python API and the Cookbook Cheat Sheet by adding links between them as well as missing information regarding to:
1) a Summary (e.g. found at Processing Algorithms Documentation on QGIS User Guide); 2) a Discussion/Usage (e.g. Processing Algorithms Documentation and Cook Book); 3) Syntax (e.g. QGIS Python API); 4) code example (e.g. Cheat Sheet and other parts of official documentation, other source of samples);
The aim is to have it for every processing algorithm tool, a path that may connect through all three QGIS official documentation (when necessary) to provide a smooth way to conduct the beginner from the cookbook to the QGIS Python API. This proposal may embrace three of the eight examples of topics: Updating and improving documentation; Improving API documentation; Helping new QGIS devs to get started with improved developer documentation and utilities.
The Need For Syntax Along With Code Sample For Beginners
When I started to program for GIS uses (about 7 years ago) I got used to the way the documentation of ArcPy was (and still is), explaining what a particular function would do, explaining its syntax, arguments types and with a clear simple code sample of its use. With basic Python and knowing what I need to do, I could look at the documentation and do it. When I started to work with QGIS, I got lost with the difference between the ArcPy and the QGIS documentation. Something what took me few minutes to perform with ArcPy, now took me hours of research and attempts. Things may get even harder when English is not your first language. So if we have in the official documentation more samples of code along with its syntax (API), especially for every processing algorithm tool that the user is already used to, the experience for those that are looking to start or already have an intermediate knowledge of Python will be greater.
Proposed Solution
Add sample of code and links between documentation (QGIS Python/API, QGIS User Guide and PyQGIS Cookbook) providing a path to have: Summary, Discussion/Usage, Syntax (link to the QGIS Python API) and code example for every for every processing algorithms. The steps will be:
1 - Copy examples from https://webgeodatavore.github.io/pyqgis-samples/ into the official API documentation, by placing these examples into the class doxygen documentation. This also benefits the c++ documentation, and keeps the examples close to the code so that they can be easily updated and revised if the API changes. 2 - Improve the Processing algorithm documentation by adding Python code examples showing use of the algorithms 3 - Add links between documentation.
Example(s)
Here we have a brief comparison between the QGIS processing algorithm documentation and the ArcGIS Toolbox documentation: Comparing the documentation the ArcGIS docs at https://desktop.arcgis.com/en/arcmap/10.3/tools/analysis-toolbox/clip.htm, an the equivalent in QGIS would be the Processing algorithm documentation (not the Python cookbook or the API docs). I.e. https://docs.qgis.org/3.10/en/docs/user_manual/processing_algs/gdal/rasterextraction.html?highlight=clip We can notice a the difference in the presentation of the information to the reader (e.g. the QGIS ones don't include any Python code examples on how to run those algorithms). The ArcPy documentation tends to have a pattern of Summary, Discussion/Usage, Syntax and code example. This pattern seems to make things clear to a beginner developer, specially the syntax and the samples of code.
Affected Files
(required if applicable)
Performance Implications
(required if known at design time)
Further Considerations/Improvements
(optional)
Backwards Compatibility
(required)
Issue Tracking ID(s)
(optional)
Votes
(required)