Placeholder for GSIP-163 - Internal Documentation Provider
https://github.com/geoserver/geoserver/wiki/GSIP-163
I added a few more ideas to consider.
On 2017-09-19 09:45 AM, Ian Turton wrote:
>
> GeoTools / GeoWebcache / GeoServer Meeting 2017-09-19
>
>
> Attending
>
> *
>
> Ian Turton
>
> *
>
> Jody Garnett
>
> *
>
> Kevin Smith
>
> *
>
> Torben Barsballe
>
> *
>
> Jukka Rahkonen
>
>
> Agenda
>
> 1.
>
> beta released
>
> 2.
>
> Swagger REST API docs
>
> 3.
>
> Release schedule
>
>
> Actions from last Meeting
>
> *
>
> Jody: (done) beta release, blocked on GWC security issues
>
> *
>
> Nicolai: Write a proposal for API Change to FactoryRegistry
>
> *
>
> Jody: Create draft FOSS4G blog post, kudos to Andrea
>
>
> Actions
>
> *
>
> Action (who?): Get ssh access to provide build box with “geotools”
> git user?
>
> *
>
> Torben: try this on core, send example to list and ask for help on
> extensions
>
> *
>
> Kevin: Create a GSIP placeholder page for next release about
> bundling API docs and User docs as optional extensions for GeoServer
>
> *
>
> Torben and Jody...: 2.12 RC1 (Week of Sept 25)
>
> *
>
> Ian (and Kevin?): 2.12 Release (Week of Oct 2)
>
> *
>
> Jody: Update release schedule
>
>
> Beta Released
>
> Thanks for doing the release Torben (and Andrea). Thanks to David Vick
> (with Devon, Torben) for completing the GWC migration restlet → spring.
>
>
> Trouble:
>
> *
>
> GWC migration took longer
>
> o
>
> Integration with GeoServer resulted in duplicate contexts
>
> o
>
> We were not reading the request the right way so the body
> right way, changed to request parameter
>
> *
>
> JTS 1.14 broke our single dimension use of DefaultCoordinateSequence
>
> o
>
> Introduced JTS utility class method and avoided direct use of
> JTS Factory
>
> o
>
> Probably would of been cleaner to add logic/wrapper to
> DefaultFactoryFinder
>
> *
>
> Documentation change to ant / maven needed updated build scripts
>
> o
>
> fixed with torben
>
> *
>
> GeoTools publish build needs credentials to publish tag
>
> o
>
> Action: Get ssh access to provide build box with “geotools”
> git user?
>
>
> Links:
>
> *
>
> http://blog.geoserver.org/2017/09/15/geoserver-2-12-beta/
>
>
> Technical debt, work to do before release?
>
> *
>
> Complete swagger docs, in many many places, see next agenda point
>
> *
>
> GEOS-8215 <https://osgeo-org.atlassian.net/browse/GEOS-8215>-
> shows a design problem with “default” mime type for a process input
>
> o
>
> Can use you use factory get priority? To get a consistent
> array order …
>
> *
>
> GEOS-8291 <https://osgeo-org.atlassian.net/browse/GEOS-8291>-
> release data dir style linking issue
>
>
> Swagger REST API docs
>
> Rest API Spreadsheet
> <https://docs.google.com/spreadsheets/d/1q9HV5cjMhh94zQW4H_u9SH-sUsoM0zrf4bmbdGjqtHM/edit#gid=0>
>
>
> Status:
>
> *
>
> Torben is 1/3 of the way through checking core
>
> o
>
> styles, layers and importer are remains
>
> *
>
> John is 3/4 of the way throw GWC docs
>
>
> What to check API
>
> *
>
> Missing endpoints that are undocumented
>
> *
>
> Check docs against the code
>
> o
>
> find missing query parameters
>
> o
>
> Undocumented features in the REST API
>
> o
>
> Documented functionality that is not implemented
>
> *
>
> Model output
>
> *
>
> check doc page links to complete list of api/1.0.0 docs
>
> What check to examples:
>
> *
>
> Examples migrated from CURL, Python, Java, Ruby → Endpoint with
> examples of CURL, …
>
>
> Open questions:
>
> *
>
> How to document connection parameters for DataStores?
>
> *
>
> Swagger provides a generic key/value map
>
> *
>
> Idea: keys form an enum, enum documents the values
>
> o
>
> This does not work well as a distinct set of keys is required
> for each format
>
> *
>
> Ideas: Example of each kind of DataStore
>
> o
>
> Limit to the formats that come out of the box? Or include
> supported extensions?
>
> o
>
> Link to the GeoServer RST pages pages to document parameters
>
> +
>
> May need to create this
>
> +
>
> Can we GeoTools RST? It is not complete either ...
>
> o
>
> Minimal example of creating each kind of DataStore
>
> +
>
> This is what people will use
>
> o
>
> Maximal example of updating each kind of DataStore
>
> +
>
> Use this to document parameters
>
> o
>
> Can we link to user guide to document parameters:
>
> +
>
>
> http://docs.geoserver.org/latest/en/user/data/database/postgis.html#using-default-connection
>
> +
>
>
> http://docs.geoserver.org/latest/en/user/data/database/index.html#data-database
>
> *
>
> Idea: Can we make a heading just for the table and combine forces
> and document once for GUI and REST API
>
> o
>
> Q: What about when key does not match gui label?
>
> o
>
> Q: What about keys that do not appear in the gui?
>
> o
>
> Q: Can we automatically generate a table based the live
> DataStoreFactory parameters.
>
> +
>
> Yes it is how we maintain function list in GeoTools
>
> o
>
> So this approach would be to generate format reference pages
> in the REST API section of the restructured?
>
> *
>
> How to include API in download doc bundle?
>
> o
>
> The website uses a javascript application - probably need a
> GISP for this
>
> +
>
> Can we include this in the geoserver app bundle? This is
> possible it is just an html page with a javascript app
> that reads, displays yaml
>
> +
>
> Could link to it from the html output?
>
> +
>
> This would allow swagger examples to run :)
>
> +
>
> As an extension? Detect docs in data directory and link …
>
> +
>
> As an extension that includes docs ...
>
> o
>
> Maven pom.xml genrates api docs (looks bad) but we can include
> that in the standalone documentation
>
>
> Result of discussion:
>
> *
>
> Provide an example of creating each datastore
>
> o
>
> Do not document connection parameters this release because we
> do not have a good approach
>
> o
>
> Idea: Try Enum + Reference Approach below
>
> +
>
> Action: Torben - try this on core, send example to list
> and ask for help on extensions
>
> *
>
> About shipping API docs, just focus on shipping for the website
> this release
>
> o
>
> Action: Kevin - Create a GSIP placeholder page for next
> release about bundling API docs and User docs as optional
> extensions for GeoServer
>
>
> Enum + Reference Approach
>
>
> MetadataEntry:
>
> type: object
>
> title: entry
>
> properties:
>
> '@key':
>
> title: key
>
> type: string
>
> enum:
>
> - buffer
>
> description: Key used for metadata entry, additional keys are
> added over time
>
> '$':
>
> title: text
>
> type: string
>
> description: Text value for provided key Valid text depends
> on key used. Example {'@key'='buffer','$'='5'}") or <entry
> key="buffer">5</entry>
>
>
>
> So we would make a connection parameter definition for each connection
> parameter of each format (Shapefile, PostGIS, DB2, etc..). We may even
> be able to reuse the database connection parameters this way if we are
> tricky ...
>
>
> And then when documenting datastores endpoint we would make a list
> that “refs” each of the connection parameter definitions.
>
>
> Release schedule
>
> Not much response to the email thread:
>
> *
>
> Asked about when to do RC1, considered tomorrow Wednesday?
>
> o
>
> Note: New branches and jobs takes a bit more than usual
>
> *
>
> Volunteers needed
>
> o
>
> Torben may be available after swagger review (after Friday)
>
> o
>
> Kevin is just back from holiday and does not know his
> availability yet ...
>
> o
>
> Jody is on holiday next week and can be available (sigh)
>
> o
>
> Ian has work work deadlines but can help week of Oct 2nd
>
>
> Looks like we can somehow make an RC1 the week of September 25th
>
> *
>
> Action: 2.12 RC1 A combination of Torben and Jody …
>
>
> And a release the week of October 2nd
>
> *
>
> Action: 2.12 Releasea combination of Ian (and Kevin?)
>
>
> Action:Jody to update release schedule
>
>
> --
> Ian Turton
>
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>
>
> _______________________________________________
> Geoserver-devel mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/geoserver-devel
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Geoserver-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
