Giters

qgis / QGIS-Enhancement-Proposals

QEP's (QGIS Enhancement Proposals) are used in the process of creating and discussing new enhancements for QGIS

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

QGIS Server and services documentation

pblottiere opened this issue · comments

commented

QGIS Server and services documentation

Date 2021/03/10

Authors

Contact blottiere dot paul at gmail dot com

Maintainer @pblottiere

Version QGIS 3.22

Summary

The main page of QGIS Server documentation about services is not complete and needs some love. The aim of this proposal is to complete the documentation by adding all services, requests and parameters available for QGIS Server.

Proposed Solution

For the WMS service:

  • add documentation for the undocumented requests GetCapabilities, GetSchemaExtension, GetStyle(s) and DescribeLayer
  • update the documentation of GetLegendGraphic(s) and GetProjectSettings to have the same format than GetMap and others

For the WFS service:

  • add documentation for the undocumented requests GetCapabilities, DescribeFeatureType and Transaction
  • update the documentation of GetFeature

For the WMTS service:

  • update the documentation of all requests to be in sync with the GetMap format (links in table of parameters, ...)

For the WCS service:

  • add documentation for this undocumented service for all requests (GetCapabilities, DescribeCoverage and GetCoverage)

Global documentation:

  • update/split/move Extra parameters supported by all request types, REDLINING and External WMS layers chapters

Affected Files

commented

It's unclear what this one adds to the FOSS projects. As far as I can see it's just copy/pasting from the OGC specs. This has already been done by GeoServer: https://docs.geoserver.org/latest/en/user/services/wms/reference.html
So why not just take theirs? It's all the same except some of the defaults, and they're only listed for some (on either project) anyway. Could be done in an afternoon if you just strip out the non-obvious defaults.

Here you are; they're rst too:
https://github.com/geoserver/geoserver/tree/main/doc/en/user/source/services

Reinventing the wheel (or more specifically, re-writing it) doesn't seem like a good use of resources.

commented

Hello @mohmad-null,

As far as I can see it's just copy/pasting from the OGC specs.

Acutally QGIS Server is not compliant with WFS, WMTS and WCS OGC specs. Some parameters are not implemented at all and some others are not properly implemented (otherwise we'd be compliant :)). Moreover, QGIS Server adds a lot of custom requests and parameters according to services which also need to be documented.

So here the aim is to write an accurate QGIS Server documentation (i.e what is really implemented), not just some copy/pasting from OGC specs. And that means precisely reading and understanding 30k loc (more or less).

Reinventing the wheel (or more specifically, re-writing it) doesn't seem like a good use of resources.

Of course I agree. Some could even argue that QGIS Server is not useful because of MapServer and GeoServer, so why should we spend money on its documentation?

commented

So here the aim is to write an accurate QGIS Server documentation (i.e what is really implemented), not just some copy/pasting from OGC specs. And that means precisely reading and understanding 30k loc (more or less).

Surely the most resource efficient way to do this is, as mohmad-null said, to just copy/paste the OGC specs/GeoServer docs and then make changes to the docs as/when QGIS' non-compliance requires? QGIS Server may not be actually compliant but it certainly should be mostly compliant which means I would then question the value of spending €2,000 to get correct those final little niggles. Especially when that 2k could close several of the > 1,200 open bugs.

And that means precisely reading and understanding 30k loc (more or less).

This is a good example of why things should be properly documented at development time as is best practice. It's a huge waste of limited resources to require going back over not-even-old code just to document what it does when the developer should have done that in the first place when it was all fresh in their mind and they had the specs in front of them.

commented

I would then question the value of spending €2,000 to get correct those final little niggles.

I would appreciate not to discuss this issue again and again - at every new round of QGIS grants. It is up to the QGIS voting members to decide how they want to spend the funds.

There are pros and cons for QGIS server, UMN Map Server and Geoserver and each of them has its strengths' and their reasons for their respective existence.

One could also argue that Geoserver was a waste of resources when UMN map server already existed (note that I don't claim that, because Geoserver does certain things better than UMN and vice versa, and it is the same with QGIS Server). Diversity is good to have in the OSGeo eco system. At the end it is the users, funders and developers who decide if a platform is relevant to them and should stay alive and prosper (or not).

commented

I would then question the value of spending €2,000 to get correct those final little niggles.

I would appreciate not to discuss this issue again and again - at every new round of QGIS grants. It is up to the QGIS voting members to decide how they want to spend the funds.

(Ignoring the fact you quote me out of context there), but isn't this the "QEP discussion phase"? Isn't the point of discussion to discuss all components, including their financial value? What's the purpose of a discussion phase if it's just an echo chamber?

There are pros and cons for QGIS server, UMN Map Server and Geoserver and each of them has its strengths' and their reasons for their respective existence.

I would like to suggest that you re-read my post and note that you're the one digging up an old conversation, not me.

I'd like to highlight that I haven't actually questioned the purpose of QGIS Server in this thread (I must admit I was going to but removed that before posting my comment as it wasn't constructive); only Paul did via a rhetorical device, and now you by quoting me out of context.
Go read my post again and you'll see that I've simply suggested that this particular ticket isn't worth the asking price because it can be > 95% satisfied by way of a copy/paste job. Surely that's worth discussing? At no point have I suggested the work should not been done (again, re-read my post if you don't believe me; you can see it hasn't been edited), only that it can be done with far less work than can justify a €2,000 outlay.

commented

(Ignoring the fact you quote me out of context there), but isn't this the "QEP discussion phase"? Isn't the point of discussion to discuss all components, including their financial value? What's the purpose of a discussion phase if it's just an echo chamber?

Yes, discussion is fine. But it should focus on the contents of the proposal and technical issues.

commented

(Ignoring the fact you quote me out of context there), but isn't this the "QEP discussion phase"? Isn't the point of discussion to discuss all components, including their financial value? What's the purpose of a discussion phase if it's just an echo chamber?

Yes, discussion is fine. But it should focus on the contents of the proposal and technical issues.

Which is exactly what I've done, hence my confusion.

commented

I'm using QGIS server since a few months and like it very much so far, but to start using it was a lot of trying things out and digging in the code because of the minimal documentation available at this time.

While the documentation is getting steadily better, there are still a lot of things I'm discovering which are not documented.

So here the aim is to write an accurate QGIS Server documentation (i.e what is really implemented)

I'm +1 for this proposal and I also think the funds would be very well spend, because a complete documention as described would save people a lot of time and make it easier to start with QGIS server.

This is a good example of why things should be properly documented at development time as is best practice. It's a huge waste of limited resources to require going back over not-even-old code just to document what it does when the developer should have done that in the first place when it was all fresh in their mind and they had the specs in front of them.

Agree, but as this isn't currently the case for all parts of the services documentation, this proposal makes even more sense to achieve a correct and complete base for future "documentation at development time".

commented

+1 with @pathmapper . +1 also with @andreasneumann , the ressource allocation debate is done when voting.
And honestly, making great user documentation is really time consuming, thus expensive. The amount proposed here seems pretty fair to me (from a French point of view), and probably, as always in Grants, will not cover all the work done.

commented

I agree with the claim that documentation should be written while developing the new feature, we are trying to do that now. But QGIS Server code is a mixture of new and relatively old code which was written at a time when the requirements for documentation were not so strict as they are now.

The main point here is to have a reference documentation for all supported standard methods plus all the custom (vendor) QGIS server extensions to the protocol.

About the money, my gut feeling is that the amount we ask is way below the time we will spend on it and that there will be a fair amount of volunteer work spent on this task.

commented

I'm not a QGIS contributor, but I can give a qgis server user point of view (I'm using it in my web dev project, either with qwc2 or without).

I do think a correct services documentation for qgis server is very important for two main reasons:

  • an OGC spec is not really suitable for users like me. There's a space between not documenting anything that is in the spec and copy-pasting it. By the way, in this aspect, I think geoserver is doing a great job presenting these services in a suitable way for its users, which brings me to my second point.
  • having a good and clear documentation is a very important "selling" point. If people go to geoserver doc to understand OGC services, they'll be much more likely to choose that solution when designing their systems. Conversely, it'll be easier for me to convince customers to choose qgis server if quality of the doc is great (not saying it's not already, but it's missing in several aspects).

For this last reason, I tink money spent in documentation should be seen as an investment rather than a waste of resources. And of course, even though the point has been made already, I cannot stress enough the importance for me to document where qgis server doesn't follow or add services to the specs.

commented

One quick point: The page being referenced in this QEP isn't actually about how to setup/configure/use QGIS Server. It's basically only useful to people who are building web-services that are bespoke expanding on QGIS Server, but not necessarily aiming for compatibility with other servers. It's of no use to folks installing/deploying the servers.

I repeat that I'm very much for documentation (I think commits shouldn't be accepted without concomitant documentation (and unit tests!)). However, given the woeful state of the QGIS Server documentation (there seem to be all of 8 pages(!), and the one we're talking about is already several times longer than the rest combined!), it seems odd to want to prioritise the page that is 95% covered by at least three other docs (GeoServer, MapServer, OGC specs; they are meant to be interchangable after all) and that is only going to possibly help a very small portion of the QGIS Server userbase.

Surely if the QGIS Server Docs need work (and they do), the resources would be better put into other aspects of it, like install, config, plugins, or even security (there's not a single item in the entire doc telling a user how to secure their install. In 2021!).

(And I say all this as someone who has written multiple OGC service ingestors, so who would actually need to know about services from this perspective.)

commented

My 2c: the quoted 2k price for this piece of work sounds completely reasonable, given then amount of work required and the very specialised knowledge required to do it 👍

commented

Hi @pblottiere and @elpaso, have you already sent a final report for this funded enhancement? It would be great if you could add a link in qgis/PSC#56.

commented

The grant report of this QEP is here: https://lists.osgeo.org/pipermail/qgis-psc/2022-January/009626.html.

I'll add a link in qgis/PSC#56.

Thanks!