onegeology / documentation Goto Github PK

OneGeology Documentation

Home Page: https://onegeology.github.io/documentation/

License: Creative Commons Attribution Share Alike 4.0 International

documentation's Introduction

OneGeology documentation for users and service providers.

The source files in this repository are used to build documentation for OneGeology users and service providers which is published to https://onegeology.github.io/documentation/.

Source files are written in reStructuredText and built into HTML pages using the Sphinx documentation generator with the Read the Docs theme.

Some of the reStructuredText was converted from pre-existing HTML files using pandoc as below:

pandoc --extract-media=appendixb -s -t rst https://onegeology.org/wmsCookbook/appendixB.html -o appendixb.rst

Building the documentation locally

If you have Docker installed you can use the example Dockerfile.sphinx to build the documentation locally.

# To build the container
docker build -f Dockerfile.sphinx -t sphinxrtd .

# To build the documentation using the built container
cd docs
docker run --rm -v $PWD:/docs sphinxrtd make html

Otherwise you should follow the Sphinx documentation to set up a local build system and then add the sphinx_rtd_theme.

Publication of changes to main site

The source reStructuredText files are transformed using Sphinx via Gitub Actions CI/CD to web pages hosted on GitHub pages. When changes are merged into the master branch the GitHub Actions configured in .github/workflows/gh-pages.yml create the content of the gh-pages branch.

Process for initial set up of publishing workflow

follow Sphinx quickstart
save to GitHub repo
edit repo settings to enable GitHub pages from gh-pages branch.
Create .github/workflows/gh-pages.yml
Create SSH keys in Linux/Putty
In repo settings>deploy add a=deply key such as "ghpagesdk" and copy/paste public key hash
In repo settings>secrets add a secret key with same name "ghpagesdk" and copy/paste private key hash.
make a commit to the master brach and should all be working.

documentation's People

Contributors

Stargazers

Watchers

Forkers

koalageo

documentation's Issues

Broken link in Simple Feature WFS (ESRI) section

https://onegeology.github.io/documentation/providingdata.html#id84

For more information on how to create a simple feature WFS service and how to edit its GetCapabilities document, go to the WMS section of this cookbook or to ESRI’s documentation about WFS services.

The WFS services link in the above text is broken. currently going to:

http://server.arcgis.com/en/server/latest/publish-services/windows/wfs-services.htm

Document use of MetaSearch plugin in using QGIS section

Test and document the use fo find all OneGeology services in the OneGeology Portal Catalogue.

Remove references to 'levels'

Cookbooks talks about level 1 and level 2 services, aimed at WMS and complex feature WFS, but now we have many more options, so these no longer seem relevant.

Reword text with level 1/level 2

for example participating.rst

Missing information on required ports?

Original cookbook (https://onegeology.org/wmsCookbook/1_2.html) has statement on required ports to be used by registered services, but latest cookbook doesn't seem to have replicate any such information.

If standard ports are still required (or if there is any restriction) re-add this content to documentation

ref: OneGeology/TechnicalDiscussion#79

Changes to DS_TOPIC documentation

Ref: https://onegeology.github.io/documentation/providingdata.html#service-provision-onegeology-profile-layer-keywords

Currently states:

We anticipate that most layers would have a DS_TOPIC@geoscientificinformation keyword.

Change case of keyword to:

We anticipate that most layers would have a DS_TOPIC@geoscientificInformation keyword.

In the following text, the link no longer resolves to a list of iso keywords

A good reference to the categories and what they represent is found at: https://gcmd.nasa.gov/add/difguide/iso_topics.html.

Perhaps use:

https://apps.usgs.gov/thesaurus/thesaurus-full.php?thcode=15

Title hierarchy

The title levels do not currently properly represent the structural hierarchy of the sections of the cookbook. Partly this arose from merging several separate pages into single long ones and some are due to the conversion of HTML pages into ReST.

Use the convention for title levels at https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections from the Python style guide.

Add producing Complex Feature WFS using ArcGIS for INSPIRE extension

Currently only producing an INSPIRE View service is covered.

Discoverability of exemplar datasets

I knew they existed, but finding the page where they are mentioned is buried. Need to make more obvious links to content at:

ftp://ftp.bgs.ac.uk/pubload/OneGeology/

Check ArcGIS GetCapabilities response behaviour

In section https://onegeology.github.io/documentation/providingdata.html#edit-the-getcapabilities-document is written:

We have found that, if you make a GetCapabilities request using external capabilities files, it always defaults to version 1.1.0, even if you specify a different version as a url parameter. For instance, http://[my_server]s:6080/arcgis/services/[folder_name]/BGS_EMODnet_bathymetry/MapServer/WCSServer?request=GetCapabilities&service=WCS&version=2.0.1 will return the GetCapabilities document for version 1.1.0 (if available, otherwise you will get an error), even though we’ve created the version 2.0.1 of the document. The only exception is version 1.0.0, which does return the correct version of the GetCapabilities document if specified in the url.

However, the correct query for a WCS v2 GetCapabilities request should use the AcceptVersions parameter as below. So we should check the expected vs actual behaviour, document that, and, if appropriate file a bug report with ESRI.

http://[my_server]s:6080/arcgis/services/[folder_name]/BGS_EMODnet_bathymetry/MapServer/WCSServer?request=GetCapabilities&service=WCS&AcceptVersions=2.0.1,1.1.0,1.0.0&

Review mentions of OneGeology Europe

Apart from #20 there are some other references to OneGeology Europe. Consider whether they need removing as the project no longer exists or whether they can remain as historical references or arbitrary examples.

In the ContactView feature table (https://onegeology.github.io/documentation/providingdata.html#contactview-features) under the contactType_uri it says there is no INSPIRE vocabulary but mentions what OneGeology Europe project used. Should it just say use the CGI vocabulary and remove any reference to what OneGeology Europe did?

In the ShearDisplacementView and GeologicUnitView feature tables (https://onegeology.github.io/documentation/providingdata.html#sheardisplacementstructureview-features and https://onegeology.github.io/documentation/providingdata.html#geologicunitview-features) below the representative...Age_uri rows, OneGeology Europe is mentioned as it was the source of additional PreCambrian Epoch age terms. Should double check the CGI vocabularies are still split in two like this and consider whether to retain reference to OneGeology Europe. Double check the INSPIRE vocabulary includes those extra terms. Maybe rephrase to say that the ics ones are those found in the official ICS chart and the other ones were added because of requirements of OneGeology Europe and are included in INSPIRE vocabulary?

At the end of the Core TC211/ISO:19115 Metadata section of the OneGeology profile (https://onegeology.github.io/documentation/providingdata.html#core-tc211-iso-19115-metadata) OneGeology Europe participants are requested to note extra requirements of INSPIRE metadata. Probably this should be changed to refer to any services that want / have to conform to INSPIRE requirements.

The MapServer documentation at https://onegeology.github.io/documentation/providingdata.html#handling-fields-for-which-you-have-no-data mentions OneGeology Europe not requiring some data that GeoSciML-Lite does need. Perhaps this should be rephrased just as general advice for anyone who doesn't have data for some GeoSciML-Lite required field?

The example MapServer configuration snippets in https://onegeology.github.io/documentation/providingdata.html#configuring-group-layering have abtracts referring to the data coming from OneGeology Europe work. These are harmless and could be left as arbitrary example abstract text for a service.

In the Apache reverse proxy section (https://onegeology.github.io/documentation/providingdata.html#using-apache-http-server-as-a-reverse-proxy) there is an example of reverse proxying the BRGM 1GConnector. This is just an arbitrary example in some ways but probably a bit confusing as an out-of date reference? Just remove it?

Document where GeoServer puts metadata entered in GUI in GetCapabilities responses

The different bits of text entered in service setup GUI sections get put into different parts of the GetCapabilities response for different services and versions. Need to document this behaviour so we know what goes where.

This may lead to recommendations for what is most important and what to put where for 1G documentation and possible edits to GeoServer documentation itself?

Will need to note version against which last checked.

Remove reference to OneGeology Europe in GEMET based layer keywords section

In the layer keywords section of the OneGeology profile (https://onegeology.github.io/documentation/providingdata.html#service-provision-onegeology-profile-layer-keywords) a specific requirement on OneGeology Europe participants is made to choose suitable terms from the GEMET thesaurus based list in Appendix I. OneGeology Europe no longer exists as a project; instead say all participants should use.