Skip to content

Commit

Permalink
[GEOS-11221] mkdocs preflight rst fixes (#7429)
Browse files Browse the repository at this point in the history
* rst: small correction to sphinx-build content

* rst: working on installation docs translation

* rst: update external links and windows file references

* rst: fix fenced div use for docer installation page

* rst: remove instructor nodes double directive

* rst: remove inline images

* rst: Use code formatting of example to avoid substitution warning

* rst: Fix invalid anchors

* rst: doc and ref fixes

* rst: heading clean for clean conversion

* rst: clean up stray anchor

* rst: fixing broken links

* rst: public review

* rst: toubleshooting feedback

* rst: address pandoc warning on value toc reference

* rst: QA unintensional blockquote indenting

* rst: prefer use of literalinclude

* rst: fix broken links

* rst: very simple list-table use

* rst: layerpreview fixes

* rst: upgrade used line-blocks to list files

* rst: ensure include snippets are rst files

  This required addition of exclude_pattern to preven to orphaned page generation

* rst: extlink url fix

* rst: remove tables from imagemosiac configuration

  The tables were too complicated and pandoc was converting to grid-tables which are unsupported by mkdocs.

* rst: fix parsed-literal \-\- glitch

  This escape is unncessry and did not convert cleanly to mkdocs

* rst: indent and line end issues for docker.rst

* rst: imagemoasic configuration example use of blockquote rather than note

* rst: fix links and guilabel for gdal.rst page

* rst: postgis fix link to jndi standard

  Link was to sun microsystems documentation

* rst: msql simplify table of connection parameters

* rst: oracle fix broken link and list indent

* rst: sqlserver simplify connection parameter table

* rst: app-schema fix reference to app-schema-cache

* rst: fixing mapping-file table and broken link

* rst: sqlserver fix code-block (it was actually a block quote)

* rst: imagemosaic/configuration try definition list presentation of complex parameters

* rst: geopkg.rst header-rows missing

* rst: imagemosaic example indenting

* rst: raster.rst - kbd tag was intended for keypresses not text input

* rst: status page formatting/content update

  The figure captions were coming out as a block quote. Fixing by breaking into two headings.

* rst: docker feedback on community modules

* rst: pandoc pipe tables do not support empty cells

* rst: featurepregen relative doc link

* fix geopackage broken link

* rst: imagemosaic/configuration of tables to definition lists

The automatic conversion is now sufficent

* Update win_binary.rst

---------

Signed-off-by: Jody Garnett <jody.garnett@gmail.com>
Co-authored-by: Peter Smythe <petersmythe@users.noreply.github.com>
  • Loading branch information
jodygarnett and petersmythe authored Mar 1, 2024
1 parent a1db4da commit 0acbc54
Show file tree
Hide file tree
Showing 93 changed files with 924 additions and 954 deletions.
498 changes: 261 additions & 237 deletions doc/en/user/source/community/backuprestore/usagerest.rst

Large diffs are not rendered by default.

22 changes: 11 additions & 11 deletions doc/en/user/source/community/cog/cog.rst
Original file line number Diff line number Diff line change
Expand Up @@ -123,13 +123,13 @@ HTTP client configuration (based on `OkHttp client <https://square.github.io/okh

* - Environment Variable
- Description
* - IIO_HTTP_MAX_REQUESTS
* - `IIO_HTTP_MAX_REQUESTS`
- The maximum number of requests to execute concurrently. Above this requests queue in memory, waiting for the running calls to complete. (Default 128)
* - IIO_HTTP_MAX_REQUESTS_PER_HOST
* - `IIO_HTTP_MAX_REQUESTS_PER_HOST`
- The maximum number of requests for each host to execute concurrently. (Default 5)
* - IIO_HTTP_MAX_IDLE_CONNECTIONS
* - `IIO_HTTP_MAX_IDLE_CONNECTIONS`
- The maximum number of idle connections. (Default 5)
* - IIO_HTTP_KEEP_ALIVE_TIME
* - `IIO_HTTP_KEEP_ALIVE_TIME`
- The Keep alive time (in seconds), representing maximum time that excess idle threads will wait for new tasks before terminating. (Default 60)

AWS S3 Client configuration
Expand All @@ -145,19 +145,19 @@ On the table below, replace the "$ALIAS$" template with HTTP or HTTPS or S3 if y

* - Environment Variable
- Description
* - IIO_$ALIAS$_AWS_CORE_POOL_SIZE
* - `IIO_$ALIAS$_AWS_CORE_POOL_SIZE`
- The core pool size for the S3 Client (Default 50)
* - IIO_$ALIAS$_AWS_MAX_POOL_SIZE
* - `IIO_$ALIAS$_AWS_MAX_POOL_SIZE`
- The maximum number of thread to allow in the pool for the S3 Client (Default 128)
* - IIO_$ALIAS$_AWS_KEEP_ALIVE_TIME
* - `IIO_$ALIAS$_AWS_KEEP_ALIVE_TIME`
- The Keep alive time (in seconds), representing maximum time that excess idle threads will wait for new tasks before terminating. (Default 10)
* - IIO_$ALIAS$_AWS_USER
* - `IIO_$ALIAS$_AWS_USER`
- Default user (access key ID) for AWS basic authentication credentials
* - IIO_$ALIAS$_AWS_PASSWORD
* - `IIO_$ALIAS$_AWS_PASSWORD`
- Default password (secret access key) for AWS basic authentication credentials
* - IIO_$ALIAS$_AWS_REGION
* - `IIO_$ALIAS$_AWS_REGION`
- Default AWS region
* - IIO_$ALIAS$_AWS_ENDPOINT
* - `IIO_$ALIAS$_AWS_ENDPOINT`
- Endpoint to Amazon service or any other S3-compatible service run by a third-party

Google Cloud storage configuration
Expand Down
11 changes: 4 additions & 7 deletions doc/en/user/source/community/cog/mosaic.rst
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,8 @@ indexer.properties:

This contains the main configuration to index the datasets composing the ImageMosaic.

.. include:: src/modisvi/indexer.properties
:literal:

.. literalinclude:: src/modisvi/indexer.properties

Relevant parts:

* Cog flag specifying that the ImageMosaic is a Mosaic of COG Datasets
Expand All @@ -42,17 +41,15 @@ timeregex.properties:

The previous indexer refers to a time dimension and the related time column in the index's schema that will get populated by extracting the time value from the filename (the 8 digits, representing YEAR, MONTH, DAY) using the regex specified in the timeregex.properties file. An example of sample file for this collection as stored on the S3 bucket is 2018.01.01.tif so the time regex will reflect that. Note the 3 groups of digits and the 'format' of the date.

.. include:: src/modisvi/timeregex.properties
:literal:
. literalinclude:: src/modisvi/timeregex.properties

datastore.properties:
"""""""""""""""""""""

Due to the amount of available datasets, storing the ImageMosaic index on a DBMS is recommended, i.e. a PostGIS DB. See :ref:`mosaic_datastore_properties` section of the ImageMosaic documentation for more info.
Make sure that a DB with the name reported in the datastore is available

.. include:: src/modisvi/datastore.properties
:literal:
.. literalinclude:: src/modisvi/datastore.properties

Once the 3 files have been setup, create a zip archive with them and let's name it modisvi.zip. (Note that the files need to be in the root of the zip files, not into a subdirectory)

Expand Down
18 changes: 10 additions & 8 deletions doc/en/user/source/community/dds/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,19 +7,19 @@ This output module allows GeoServer to output imagery and terrain in formats
understood by `NASA World Wind <http://worldwind.arc.nasa.gov/java/>`_. The
mime-types supported are:

#. Direct Draw Surface (DDS) - image/dds. This format allows efficient loading of textures to the GPU and takes the task off the WorldWind client CPU in converting downloaded PNG, JPEG or TIFF tiles. The DDS compression is done using `DXT3 <http://en.wikipedia.org/wiki/S3_Texture_Compression>`_ with help from the worldwind library on server side.
#. Direct Draw Surface (DDS) - image/dds. This format allows efficient loading of textures to the GPU and takes the task off the WorldWind client CPU in converting downloaded PNG, JPEG or TIFF tiles. The DDS compression is done using `DXT3 <http://en.wikipedia.org/wiki/S3_Texture_Compression>`_ with help from the worldwind library on server side.

#. Binary Interleaved by Line(BIL) - image/bil. This is actually a very simple raw binary format produced using the `RAW Image Writer <http://www.java2s.com/Open-Source/Java-Document/6.0-JDK-Modules/Java-Advanced-Imaging/com/sun/media/imageioimpl/plugins/raw/RawImageWriterSpi.java.java-doc.htm>`_. The supplied GridCoverage2D undergoes appropriate subsampling, reprojection and bit-depth conversion. The output can be requested as 16bit Int or 32bit Float.
#. Binary Interleaved by Line(BIL) - image/bil. This is actually a very simple raw binary format produced using the `RAW Image Writer <http://www.java2s.com/Open-Source/Java-Document/6.0-JDK-Modules/Java-Advanced-Imaging/com/sun/media/imageioimpl/plugins/raw/RawImageWriterSpi.java.java-doc.htm>`_. The supplied GridCoverage2D undergoes appropriate subsampling, reprojection and bit-depth conversion. The output can be requested as 16bit Int or 32bit Float.


Installing the DDS/BIL extension
-----------------------------------

#. Download the DDS/BIL extension from the `nightly GeoServer community module builds <https://build.geoserver.org/geoserver/main/community-latest/>`_. A prebuilt version for GeoServer 2.0.x can be found on Jira - :geos:`3586`.
#. Download the DDS/BIL extension from the `nightly GeoServer community module builds <https://build.geoserver.org/geoserver/main/community-latest/>`_. A prebuilt version for GeoServer 2.0.x can be found on Jira - :geos:`3586`.

.. warning:: Make sure to match the version of the extension to the version of the GeoServer instance!
.. warning:: Make sure to match the version of the extension to the version of the GeoServer instance!

#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation.
#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation.

Checking if the extension is enabled
------------------------------------
Expand All @@ -29,10 +29,12 @@ Once the extension is installed, the provided mime-types should appear in the la
.. figure:: images/bil_dds.jpg
:align: center

The mime-types will also be listed in the ``GetCapabilities`` document::
The mime-types will also be listed in the ``GetCapabilities`` document:

<Format>image/bil</Format>
<Format>image/dds</Format>
.. code-block:: xml
<Format>image/bil</Format>
<Format>image/dds</Format>
Configuring the BIL format
------------------------------------
Expand Down
4 changes: 2 additions & 2 deletions doc/en/user/source/community/elasticsearch/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ This data store allows features from an Elasticsearch index to be published thro
Configuration
-------------

.. _config_elasticsearch:

Configuring data store
^^^^^^^^^^^^^^^^^^^^^^

Expand All @@ -23,8 +25,6 @@ Once the Elasticsearch GeoServer extension is installed, ``Elasticsearch index``
| |new_store| |
+-------------+

.. _config_elasticsearch:

The Elasticsearch data store configuration panel includes connection parameters and search settings.

.. |store_config| image:: images/elasticsearch_configuration.png
Expand Down
14 changes: 7 additions & 7 deletions doc/en/user/source/community/gdal/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -111,13 +111,13 @@ The file showcases all possible usage of the configuration elements:

* ``Format`` defines a single format, which is defined by the following tags:

* ``toolFormat``: the name of the format to be passed to gdal_translate with the -of option (case insensitive).
* ``geoserverFormat``: is the name of the output format as advertised by GeoServer
* ``fileExtension``: is the extension of the file generated after the translation, if any (can be omitted)
* ``option``: can be used to add one or more options to the gdal_translate command line. As you can see by the JPEG2000 example, each item must be contained in its own ``option`` tag. You can get a full list of options by running ``gdal_translate --help`` or by visiting the `GDAL website <http://www.gdal.org>`_). Also, consider that each format supports specific creation options, listed in the description page for each format (for example, here is the `JPEG2000 one <http://www.gdal.org/frmt_jpeg2000.html>`_).
* ``singleFile``: if true the output of the conversion is supposed to be a single file that can be streamed directly back without the need to wrap it into a zip file
* ``mimeType``: the mime type of the file returned when using ``singleFile``. If not specified ``application/octet-stream`` will be used as a default.
* ``formatAdapters``: transformations on the coverage that might need to be applied in order to successfully encode the output. The transformations are applied only if their input conditions are met.
* ``toolFormat``: the name of the format to be passed to gdal_translate with the -of option (case insensitive).
* ``geoserverFormat``: is the name of the output format as advertised by GeoServer
* ``fileExtension``: is the extension of the file generated after the translation, if any (can be omitted)
* ``option``: can be used to add one or more options to the gdal_translate command line. As you can see by the JPEG2000 example, each item must be contained in its own ``option`` tag. You can get a full list of options by running ``gdal_translate --help`` or by visiting the `GDAL website <http://www.gdal.org>`_). Also, consider that each format supports specific creation options, listed in the description page for each format (for example, here is the `JPEG2000 one <http://www.gdal.org/frmt_jpeg2000.html>`_).
* ``singleFile``: if true the output of the conversion is supposed to be a single file that can be streamed directly back without the need to wrap it into a zip file
* ``mimeType``: the mime type of the file returned when using ``singleFile``. If not specified ``application/octet-stream`` will be used as a default.
* ``formatAdapters``: transformations on the coverage that might need to be applied in order to successfully encode the output. The transformations are applied only if their input conditions are met.

The available format adapters are:

Expand Down
2 changes: 1 addition & 1 deletion doc/en/user/source/community/geopkg/output.rst
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ where the ``name`` of a known gridset is specified; or a custom gridset may be d
</grids>
</gridset>
.. _overviews:
.. _overviews:

Creating generalized tables
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down
6 changes: 3 additions & 3 deletions doc/en/user/source/community/taskmanager/developer.rst
Original file line number Diff line number Diff line change
Expand Up @@ -217,12 +217,12 @@ interface):
- ``SQL`` (protects against ';' hacking)

External Parameter Types (members of ``ExtTypes`` spring bean): \*
``dbName``: `database name <user#databases>`__ \* ``tableName``:
``dbName``: :ref:`database name <taskmanager_user_databases>` \* ``tableName``:
table name (parameter must depend on parameter of ``dbName`` type) \*
``extGeoserver``: `external geoserver <user#external-geoservers>`__
``extGeoserver``: :ref:`external geoserver <taskmanager_user_external_geoserver>`
\* ``internalLayer``: layer from geoserver catalog \* ``name``: name
qualified with namespace from geoserver catalog \* ``fileService``:
`file service <user#file-services>`__ \* ``file``: reference to file
:ref:`file service <taskmanager_user_file_services>` \* ``file``: reference to file
(parameter must dpend of parameter of ``fileService`` type)

Defining a new Parameter Type:
Expand Down
7 changes: 5 additions & 2 deletions doc/en/user/source/community/taskmanager/user.rst
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,8 @@ clustered quartz database at the same time at start-up, which is likely
to cause issues. This initialisation needs to happen only once for the
entire cluster.

.. _taskmanager_user_databases:

Databases
~~~~~~~~~

Expand Down Expand Up @@ -151,8 +153,7 @@ configured as follows:
<property name="rawGeometryTable" ref="geomtable"/>
</bean>
.. _taskmanager_user_external_geoserver:

External GeoServers
~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -192,6 +193,8 @@ Task Manager also supports geoservers protected with keycloak:
<property name="supportMetadata" value="true" />
</bean>
.. _taskmanager_user_file_services:

File Services
~~~~~~~~~~~~~

Expand Down
9 changes: 8 additions & 1 deletion doc/en/user/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@
download = release
latest = ''
download_release = 'http://sourceforge.net/projects/geoserver/files/GeoServer/'+release+'/geoserver-'+release+'-%s.zip'
download_extension = 'http://sourceforge.net/projects/geoserver/files/GeoServer/'+release+'/extensions/geoserver-'+release+'-%s-plugin.zip'
download_extension = 'https://sourceforge.net/projects/geoserver/files/GeoServer/'+release+'/extensions/geoserver-'+release+'-%s-plugin.zip'
download_community = 'https://build.geoserver.org/geoserver/'+branch+'/community-latest/geoserver-'+version+'.x-SNAPSHOT-%s-plugin.zip'

# There are two options for replacing |today|: either, you set today to some
Expand All @@ -91,6 +91,13 @@
# List of documents that shouldn't be included in the build.
#unused_docs = []

# A list of glob-style patterns [1] that should be excluded when looking for source files.
# They are matched against the source file names relative to the source directory,
# using slashes as directory separators on all platforms.
exclude_patterns = [
'**/symbolizers/include/*.rst'
]

# List of directories, relative to source directories, that shouldn't be searched
# for source files.
exclude_trees = []
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ When supporting large images it is efficient to work on image subsets without lo

.. _JAIEXT:

JAI-EXT
JAI-EXT
-------

The `JAI-EXT <https://github.com/geosolutions-it/jai-ext>`_ library is open-source project which aims to replace closed source JAI project provided by Sun. The main difference between *JAI* and *JAI-EXT* operations is the support for external **Region of Interests** (ROI) and image **NoData** in *JAI-EXT*.
Expand Down
2 changes: 0 additions & 2 deletions doc/en/user/source/configuration/raster_access.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,6 @@ The Coverage Access Settings page in the Server menu in the :ref:`web_admin` pro
.. figure:: img/raster_access.png

Raster Access Settings

.. _Thread_pool_executor_settings:

.. _ImageIO_settings:

Expand Down
42 changes: 29 additions & 13 deletions doc/en/user/source/configuration/status.rst
Original file line number Diff line number Diff line change
Expand Up @@ -243,19 +243,35 @@ JVM Console

For information on the live Java Runtime Environment the :guilabel:`JVM Console` tab provides access to two useful troubleshooting tools.

Press :guilabel:`Thread Dump` for a summary of all active threads. This is primarily used to troubleshoot performance issues and a non-responsive system. This can be used to identify when significant work is happening in the background, or if threads are stuck waiting on a resource.
.. note::

.. figure:: img/thread_dump.png

Thread Dump console output


For more information on effective use see :ref:`troubleshooting`.

Press :guilabel:`Heap Dump` for an overview of memory use. This can be used to troubleshoot systems that are encountering a memory leak over time.
.. figure:: img/heap_dump.png

Heap Dump console output

* Click :guilabel:`Download` link to download the JVM Console contents.
Java Threads
^^^^^^^^^^^^

Java Threads are how CPU use is shared between outstanding work GeoServer is performing (or waiting to perform).
The "Thread Dump" is primarily used to troubleshoot performance issues and a non-responsive system.
This can be used to identify when significant work is happening in the background, or if threads are stuck waiting on a resource.

1. Press :guilabel:`Thread Dump` for a summary of all active threads.

.. figure:: img/thread_dump.png

Thread Dump console output

2. Click :guilabel:`Download` link to download the JVM Console contents.

Java Heap
^^^^^^^^^

The Java Heap is a description of dynamic (or heap) memory use.
The "Thread Dump" can be used to troubleshoot systems that are encountering a memory leak over time.

1. Press :guilabel:`Heap Dump` for an overview of memory use.

.. figure:: img/heap_dump.png

Heap Dump console output

For more information on effective use see :ref:`troubleshooting`.
2. Click :guilabel:`Download` link to download the JVM Console contents.
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ To be able to encode XML responses conforming to a GML application schema, the a
Schema downloading is now automatic for most users
--------------------------------------------------

GeoServer will automatically download and cache (see `Cache`_ below) all the schemas it needs the first time it starts if:
GeoServer will automatically download and cache (see :ref:`Cache <app-schema-cache>` below) all the schemas it needs the first time it starts if:

#. All the application schemas you use are accessed via http/https URLs, and
#. Your GeoServer instance is deployed on a network that permits it to download them.
Expand Down
18 changes: 9 additions & 9 deletions doc/en/user/source/data/app-schema/mapping-file.rst
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,7 @@ A CQL expression that is used to set the custom ``gml:id`` of the output feature

* In the absence of primary keys, this will be ``<the table name>.<generated gml id>``, e.g. ``MAPPEDFEATURE.fid--46fd41b8_1407138b56f_-7fe0``.

* If using property files instead of database tables, the default ``gml:id`` will be the row key found before the equals ("=") in the property file, e.g. the feature with row "mf1=Mudstone|POINT(1 2)|..." will have gml:id ``mf1``.
* If using property files instead of database tables, the default ``gml:id`` will be the row key found before the equals ("=") in the property file, e.g. the feature with row ``mf1=Mudstone|POINT(1 2)|...`` will have ``gml:id`` ``mf1``.

.. note:: ``gml:id`` must be an `NCName <http://www.w3.org/TR/1999/REC-xml-names-19990114/#NT-NCName>`_.

Expand Down Expand Up @@ -342,19 +342,19 @@ For example, the table below has multiple ``POSITION`` for each feature:
===== ========
ID POSITION
===== ========
ID1.2 1948-05
ID1.2 1948-06
ID1.2 1948-07
ID1.2 1948-08
ID1.2 1948-09
ID1.2 1948-05
ID1.2 1948-06
ID1.2 1948-07
ID1.2 1948-08
ID1.2 1948-09
===== ========

The configuration file uses ``isList`` on ``timePositionList`` attribute mapped to ``POSITION`` column::

<AttributeMapping>
<targetAttribute>csml:timePositionList</targetAttribute>
<sourceExpression>
<OCQL>POSITION</OCQL>
<OCQL>POSITION</OCQL>
</sourceExpression>
<isList>true</isList>
</AttributeMapping>
Expand Down Expand Up @@ -398,7 +398,7 @@ CQL functions enable data conversion and conditional behaviour to be specified i
* See :ref:`app-schema.cql-functions` for information on additional functions provided by the app-schema plugin.
* The uDig manual includes a list of CQL functions:

* http://udig.refractions.net/confluence/display/EN/Constraint+Query+Language
* http://udig.github.io/docs/user/concepts/Constraint%20Query%20Language.html

* CQL string literals are enclosed in single quotes, for example ``'urn:ogc:def:nil:OGC:missing'``.

Expand Down Expand Up @@ -427,7 +427,7 @@ Attributes with cardinality 1..N
Consider the following two tables, the first table contains information related to meteorological stations:

======== ==========
ID NAME
ID NAME
======== ==========
st.1 Station 1
st.2 Station 2
Expand Down
2 changes: 1 addition & 1 deletion doc/en/user/source/data/app-schema/solr-tutorial.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Apache Solr Tutorial
====================

This tutorial demonstrates how to use the App-Schema plugin with a Apache Solr data store. This tutorial will focus on the Apache Solr data store specific aspects, and the `App-Schema documentation <_app-schema>`_ should be read first.
This tutorial demonstrates how to use the App-Schema plugin with a Apache Solr data store. This tutorial will focus on the Apache Solr data store specific aspects, and the :ref:`App-Schema documentation <app-schema>` should be read first.

The use case for this tutorial will be to serve through App-Schema the information about some meteorological stations index in an Apache Solr core. Note that this use case is completely fictional and only used to demonstrate the Apache Solr and App-Schema integration.

Expand Down
Loading

0 comments on commit 0acbc54

Please sign in to comment.