QEP 333: Add screenshots to PyQGIS reference documentation #333
Conversation
nyalldawson
added
In Discussion
nyalldawson
changed the title
There was a problem hiding this comment.
Really nice!
It reminded me of a reverted work I did in the past: qgis/QGIS#8041
Generally I would try to keep in mind a potential usage for the user documentation too at some point.
| im.save((dest_path / 'color_box_hue.png').as_posix()) | ||
|
|
||
| return ("\nQgsColorBox using the QgsColorWidget.ColorComponent.Value component:\n\n.. image:: color_box_value.png\n" + | ||
| "\nQgsColorBox using the QgsColorWidget.ColorComponent.Hue component:\n\n.. image:: color_box_hue.png\n") |
There was a problem hiding this comment.
I think the return value should be code agnostic, a dict with file name and label.
This is more futureproof and flexible for other usage.
The sphinx part should be then generated in the sphinx code
| The ``generate_screenshot`` method must have the signature: | ||
|
|
||
| ``` py | ||
| def generate_screenshot(dest_path: Path) -> str: |
There was a problem hiding this comment.
make this "private" using double underscores?
|
cc @ThomasG77 the guy behind Webgeodatavore 😉 |
|
It would be very valuable! Would it be possible to display with a "Show snippet code" or a spoiler the code behind the screenshot ? |
I'd prefer not -- I think there'll be a moderate amount of "not best practice" code required here, in order to get things looking nice for a screenshot alone with the minimum maintenance burden. (Eg in the QgsMapLayerComboBox code above I'm just using invalid dummy memory layers, as those are sufficient to appear as a normal layer in the combo). For a future grant funding round I plan on porting the example code from the Webgeodatavore site, so at that stage we would get best-practice sample code in the documentation (all unit-tested, of course!) |
Good point! I think a lot of the work/value here will be in fleshing out the ScreenshotUtils class. Eg for my proof of concept tests it was quite a bit of work getting a This class will be kept generic and independent from the PyQGIS logic, so we could rely on it for some future documentation screenshot generation. |
@3nids The tool is still there (qgis --help). I even gave it a shot a few weeks ago, with Selma. Screenshots are generated but unfortunately still wrongly resized.
+1. |
Thanks to a concentrated effort over the last couple of years, the PyQGIS reference documentation has improved substantially. It's now a valuable, Python-developer friendly, reference, presented in a modern, sleek format.
That said, there's still much room for further improvements in the documentation!
A previously valuable resource for PyQGIS developers was the (unofficial) "PyQGIS samples" site at https://webgeodatavore.github.io/pyqgis-samples/index.html. This site included some great content, including screenshots and example code for many PyQGIS classes.
Unfortunately, this site is outdated and has not been updated for either QGIS 3.x or Qt 5, and accordingly is no longer a valuable resource. This is a shame, as the example screenshots helped PyQGIS developers find the right GUI classes for their code, and
the example code was a fantastic starting point for working with each class.
This proposal seeks to partially port the content from the webgeodatavore site over to the official PyQGIS Reference Guide, specifically the screenshot component only.
(Rendered version with screenshots at https://github.com/qgis/QGIS-Enhancement-Proposals/blob/132a86ad650144d2430afade453bdb43a1eee981/qep_333_pyqgis_screenshots.md )