Fix doc warnings.

doc/about.rst

@@ -19,7 +19,7 @@ What is its big idea?
 --------------------------------------------------------------------------------
 
 PDAL allows you to compose :ref:`operations <filters>` on point clouds into
-:ref:`pipelines <pipeline>` of :ref:`stages <stage_index>`. These pipelines can
+:ref:`pipelines <pipeline>` of stages. These pipelines can
 be written in a declarative JSON syntax or constructed using the available API.
 
 Why would you want to do that?

doc/conf.py

@@ -25,7 +25,7 @@
 def process_dimensions():
     import json, csv
 
-    data = open('../pdal/Dimension.json','rb').read()
+    data = open('../pdal/Dimension.json','r').read()
 
     data = json.loads(data)['dimensions']
 
@@ -35,7 +35,7 @@ def process_dimensions():
 
     output = sorted(output,key=lambda x: x[0])
 
-    with open('dimension-table.csv','wb') as fp:
+    with open('dimension-table.csv','w') as fp:
         a = csv.writer(fp, delimiter=',', quotechar='"', quoting=csv.QUOTE_ALL)
         a.writerows(output)
 
@@ -89,24 +89,15 @@ def read_version(filename):
 
     token = 'PDAL_VERSION_STRING'
 
-    import string
-    punct = string.punctuation
-    punct = string.punctuation.replace('.', '')
-    version = 'None'
     for line in data:
         if str(token) in line:
-            import re
-            parts = re.split('[\sd\.d\.d*]', line)
-            parts = [a.translate(None, punct) for a in parts]
-            ints = [ int (i) for i in (parts[1], parts[2], parts[3])]
-            version = '%d.%d.%d' % (ints[0], ints[1], ints[2])
+            version = re.search(r'\d.\d.\d', line).group(0)
             break
-    return '%s'%(version)
+    return version
 
 release = read_version('../CMakeLists.txt')
 version = release
 
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #language = None
@@ -282,8 +273,7 @@ def read_version(filename):
 latex_show_pagerefs = True
 
 # If true, show URL addresses after external links.
-latex_show_urls = True
-
+latex_show_urls = 'inline'
 
 # Documents to append as an appendix to all manuals.
 #latex_appendices = []

doc/development/index.rst

@@ -16,7 +16,6 @@ developing new code can be found in this section.
 .. toctree::
    :maxdepth: 2
 
-   contributors
    overview
    compilation/index
    errorhandling

doc/development/writing-reader.rst

@@ -23,7 +23,7 @@ First, we provide a full listing of the reader header.
 
 .. literalinclude:: ../../examples/writing-reader/MyReader.hpp
    :language: cpp
-   :lines:18-20
+   :lines: 18-20
    :linenos:
 
 ``m_stream`` is used to process the input, while ``m_index`` is used to track

doc/development/writing.rst

@@ -57,7 +57,7 @@ and sends it to a writer.
 
 .. literalinclude:: ../../examples/writing/tutorial.cpp
    :language: cpp
-   :lines: 45-74
+   :lines: 35-64
 
 Compiling and running the program
 -------------------------------------------------------------------------------

doc/faq.rst

@@ -12,7 +12,9 @@ FAQ
   pronounced to rhyme with "GDAL".
 
   .. it is properly pronounced like the dog though :) -- hobu
+
 |
+
 * Why do I get the error "Couldn't create ... stage of type ..."?
 
   In almost all cases this error occurs because you're trying to run a stage
@@ -46,7 +48,9 @@ FAQ
   additional memory during processing before the output can be written.
   Depending on the operation, PDAL will attempt operate in "stream mode" to
   limit memory consumption when possible.
+
 |
+
 * What is PDAL's relationship to PCL?
 
   PDAL is PCL's data translation cousin. PDAL is focused on providing a
@@ -72,6 +76,7 @@ FAQ
 .. _`GeoHipster interview`: http://geohipster.com/2018/03/05/howard-butler-like-good-song-open-source-software-chance-immortal/
 
 |
+
 * Are there any command line tools in PDAL similar to LAStools?
 
   Yes. The :ref:`pdal <apps>` command provides a wide range of features which go

doc/pipeline.rst

@@ -130,8 +130,6 @@ files from a single pipeline.  The crop filter creates two output point views
 (one for each specified geometry) and the writer creates output files
 'output1.las' and 'output2.las' containing the two sets of points:
 
-::
-
 .. code-block:: json
 
   {
@@ -230,9 +228,12 @@ For more on PDAL stages and their options, check the PDAL documentation on
   Some options allow multiple inputs.  In those cases, provide the option
   values as a JSON array.
 
-* Applications can place a ``user_data`` node on any stage object and it will be
+* A ``user_data`` option can be added to any stage object and it will be
   carried through to any serialized pipeline output.
 
+* All stages support the ``option_file`` option that allows options to be
+  places in a separate file. See :ref:`option_files` for details.
+
 Filename Globbing
 ................................................................................
 
@@ -244,6 +245,33 @@ Filename Globbing
   when a filename is provided as an option through a command-line application
   like ``pdal pipeline`` or ``pdal translate``.
 
+.. _option_files:
+
+Option Files
+................................................................................
+
+All stages accept the ``option file`` option that allows extra options for a
+stage to be placed in a separate file.  The value of the option is the filename
+in which the additional options are located.
+
+Option files can be written using either JSON syntax or command line syntax.
+When using the JSON syntax, the format is a block of options just as if the
+options were placed in a pipeline:
+
+.. code-block:: json
+
+    {
+        "minor_version": 4,
+        "out_srs": "EPSG_4326"
+    }
+
+When using the command line syntax, the options are specified as they would
+be on the command line without the need to qualify the option names with
+the stage name:
+
+.. code-block:: none
+
+    --minor_version=4 --out_srs="EPSG_4326"
 
 Extended Examples
 --------------------------------------------------------------------------------
@@ -512,11 +540,6 @@ PDAL. Readers follow the pattern of :ref:`readers.las` or
 :ref:`readers.oci`, with Filters using :ref:`filters.reprojection` or
 :ref:`filters.crop`.
 
-.. note::
-
-    :ref:`stage_index` contains a full listing of possible stages and
-    descriptions of their options.
-
 .. note::
 
     Issuing the command ``pdal info --options`` will list all available

doc/project/contributors.rst

@@ -31,7 +31,7 @@ new feature development of PDAL over the past couple of years.
 
 
 `Michael Gerlek`_ helped bootstrap PDAL by providing its first design, basic
-primitive objects, and first :ref:`stage <stage_index>` implementations.
+primitive objects, and first stage implementations.
 
 .. _`Michael Gerlek`: http://github.com/mpgerlek
 
@@ -42,7 +42,7 @@ primitive objects, and first :ref:`stage <stage_index>` implementations.
 
 `Bradley Chambers`_ from `RadiantSolutions`_ has contributed numerous features
 and capabilities to the PDAL project, including :ref:`Poisson sampling
-<dart-throwing-tutorial>` and :ref:`Progressive Morphological Filters
+<filters.sample>` and :ref:`Progressive Morphological Filters
 <pcl_ground>`. He is also a prolific :ref:`tutorial` writer.
 
 .. _`Bradley Chambers`: https://github.com/chambbj

doc/project/docs.rst

@@ -21,14 +21,6 @@ items:
 .. _`Latex`: https://en.wikipedia.org/wiki/LaTeX
 .. _`pdflatex`: https://www.tug.org/applications/pdftex/
 
-.. note::
-
-    For the website, PDAL builds the documentation using :ref:`travis` and :ref:`docker`.
-    You can get a listing of the exact Ubuntu requirements in the `Dockerfile`_.
-    See :ref:`integration` for more detail.
-
-.. _`Dockerfile`: https://github.com/PDAL/PDAL/tree/master/scripts/docker/docbuild/Dockerfile
-
 Sphinx_ and Breathe_
 --------------------------------------------------------------------------------
 
@@ -103,39 +95,9 @@ is then served via `GitHub Pages`_.
     The website is regenerated and pushed only on the ``after_success`` :ref:`travis`
     call. If the tests aren't passing, the website won't be updated.
 
-Building With Docker
-================================================================================
-
-A :ref:`docker` image, ``pdal/docs`` contains the full compliment of requirements,
-and it is used by PDAL's :ref:`travis` continuous integration to build and commit
-new versions of the website. You can easily build the docs using Docker by
-issuing the following command:
-
-::
-
-    docker run -v /path/to/pdal/root/tree:/data -w /data/doc pdal/docs make html
-
-
-Container refresh
-................................................................................
-
-The ``pdal/docs`` container can be refreshed on DockerHub by tagging a ``docbuild``
-tag and force-pushing it to the main repository:
-
-::
-
-    $ git tag -f docbuild
-    $ git push origin -f refs/tags/docbuild
-
-.. note::
-
-    The ``pdal/docs`` container is constructed from the `Dockerfile <https://github.com/PDAL/PDAL/blob/master/scripts/docker/docbuild/Dockerfile>`__ at whatever revision the ``docbuild`` tag points to.
 
 .. _`GitHub Pages`: https://pages.github.com/
 .. _`GitHub`: http://github.com/PDAL/PDAL
-
-.. _`Digital Ocean`: digitalocean.com
-
 .. _Sphinx: http://sphinx-doc.org/
 .. _Breathe: https://github.com/michaeljones/breathe
 .. _virtual environments: https://pypi.python.org/pypi/virtualenv

doc/project/testing.rst

@@ -13,7 +13,7 @@ will have unit tests.  At the very least, each new class should have a
 corresponding unit test file stubbed in, even if there aren't any tests yet.
 
 *   Our unit tests also include testing of the command line :ref:`apps` and
-    (known) :ref:`plugins <stage_index>`.
+    known plugins.
 
 *    We use the `Google C++ Test Framework`_, but a local copy of it is
      embedded in the PDAL source tree, and you don't have to have it available

doc/python.rst

@@ -156,3 +156,4 @@ Once the environment has been created, you will be prompted to activate it. ::
 
 .. _`pip`: https://pip.pypa.io/en/stable/
 .. _`easy_install`: https://pypi.python.org/pypi/setuptools
+.. _`conda`: https://conda.io/docs/

doc/stages/filters.delaunay.rst

@@ -33,4 +33,5 @@ Example
           "filename": "output.ply",
           "faces": true
         }
+      ]
     }

doc/stages/filters.hexbin.rst

@@ -43,7 +43,7 @@ the hexbin filter:
     $ pdal pipeline hexbin-pipeline.json --metadata hexbin-out.json
 
 
-.. code-block:: json
+.. code-block:: none
 
     {
       "stages":
@@ -61,7 +61,8 @@ the hexbin filter:
           "hex_offsets": "MULTIPOINT (0 0, -32.2711 55.8952, 0 111.79, 64.5422 111.79, 96.8133 55.8952, 64.5422 0)",
           "sample_size": 5000,
           "threshold": 15
-        },
+        }
+    },
     ...
 
 

doc/stages/filters.neighborclassifier.rst

@@ -1,7 +1,7 @@
 .. _filters.neighborclassifier:
 
 filters.neighborclassifier
-===================
+==========================
 
 The neighborclassifier filter allows you update the value of the classification
 for specific points to a value determined by a K-nearest neighbors vote.
@@ -25,6 +25,7 @@ This pipeline updates the Classification of all points with classification
 1 (unclassified) based on the consensus (majority) of its nearest 10 neighbors.
 
 .. code-block:: json
+
     {
       "pipeline":[
         "autzen_class.las",
@@ -45,6 +46,7 @@ to src.las.  Any points in src.las that are not in pred.txt will be
 assigned based on the closest point in pred.txt.
 
 .. code-block:: json
+
     {
       "pipeline":[
         "src.las",