Restore ability to build properly (#99)

* Create .readthedocs.yaml

* Create .readthedocs.yaml

* Update sphinx version to be compatible with sphix_rtd_theme

* Specify dependencies

* Fix double dash formatting

* Add graphviz dependency to ensure digraphs render

* Trying again but adding a apt_package instead

* Update python to 3.11

* Maybe smartquotes is unnecessary and a single
backslash escape is enough?

* Missed a file when removing double escape

Author: sdmcgrath

.readthedocs.yaml

@@ -0,0 +1,24 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  apt_packages:
+    - graphviz
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: conf.py
+
+# We recommend specifying your dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+  - requirements: dependencies.txt

conf.py

@@ -33,7 +33,7 @@
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-# needs_sphinx = '1.0'
+needs_sphinx = '5.0'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

dependencies.txt

@@ -0,0 +1 @@
+sphinx_rtd_theme

reference/discovery-arguments.rst

@@ -7,14 +7,14 @@ For each argument the name in brackets indicates which package contributes it.
 
 .. _discovery-args_paths_arg:
 
-\\--paths [PATH [PATH ...]] [``colcon-core``]
+\--paths [PATH [PATH ...]] [``colcon-core``]
   The (non recursive) paths to check for a package.
   Use shell wildcards (e.g. ``src/*``) to select all direct subdirectories of
   ``src``.
 
 .. _discovery-args_base-paths_arg:
 
-\\--base-paths [PATH [PATH ...]] [``colcon-recursive-crawl``]
+\--base-paths [PATH [PATH ...]] [``colcon-recursive-crawl``]
   The base paths to recursively crawl for packages.
   The default value is ``.``.
   In a workspace root the subdirectories other than ``src`` (commonly
@@ -23,28 +23,28 @@ For each argument the name in brackets indicates which package contributes it.
 
 .. _discovery-args_metas_arg:
 
-\\--metas [PATH [PATH ...]] [``colcon-metadata``]
+\--metas [PATH [PATH ...]] [``colcon-metadata``]
   The directories containing a ``colcon.meta`` file or paths to arbitrary files
   containing the same meta information.
   The default value is ``./colcon.meta``.
 
 .. _discovery-args_ignore-user-meta_arg:
 
-\\--ignore-user-meta [``colcon-metadata``]
+\--ignore-user-meta [``colcon-metadata``]
   Ignore ``*.meta`` files in the configuration directory
   :ref:`$COLCON_HOME <colcon-core_colcon-home_env>`\ ``/metadata/``.
 
 .. _discovery-args_packages-ignore_arg:
 
-\\--packages-ignore [PKG_NAME [PKG_NAME ...]] [``colcon-package-selection``]
+\--packages-ignore [PKG_NAME [PKG_NAME ...]] [``colcon-package-selection``]
   Ignore packages by name as if they were not discovered.
   In contrast to being skipped using
   :doc:`package selection <package-selection-arguments>` arguments, ignored
   packages aren't considered in the dependency graph.
 
 .. _discovery-args_packages-ignore-regex_arg:
 
-\\--packages-ignore-regex [PATTERN [PATTERN ...]] [``colcon-package-selection``]
+\--packages-ignore-regex [PATTERN [PATTERN ...]] [``colcon-package-selection``]
   Ignore packages where any of the patterns match the package name.
   In contrast to being skipped using
   :doc:`package selection <package-selection-arguments>` arguments, ignored

reference/event-handler-arguments.rst

@@ -5,7 +5,7 @@ The event handlers are used by several verbs to generate any kind of output
 based on the progress of the invocation.
 For each argument the name in brackets indicates which package contributes it.
 
-\\--event-handlers [name1+ [name2- ...]] [``colcon-core``]
+\--event-handlers [name1+ [name2- ...]] [``colcon-core``]
   A list of event handlers to enable (trailing ``+``) or disable (trailing
   ``-``).
   The default is chosen by each available event handler (see

reference/executor-arguments.rst

@@ -7,7 +7,7 @@ For each argument the name in brackets indicates which package contributes it.
 
 .. _executor-args_executor_arg:
 
-\\--executor EXECUTOR [``colcon-core``]
+\--executor EXECUTOR [``colcon-core``]
   The executor to process all jobs.
   The default is chosen based on the priorities of all available executor
   extensions.
@@ -28,7 +28,7 @@ For each argument the name in brackets indicates which package contributes it.
 
 .. _executor-args_parallel-workers_arg:
 
-\\--parallel-workers NUMBER [``colcon-parallel-executor``]
+\--parallel-workers NUMBER [``colcon-parallel-executor``]
   The maximum number of jobs to process in parallel.
   The default value is the number of logical CPU cores as reported by
   `os.cpu_count() <https://docs.python.org/3/library/os.html#os.cpu_count>`_.

reference/global-arguments.rst

@@ -9,7 +9,7 @@ For each argument the name in brackets indicates which package contributes it.
 
 .. _colcon_log-base_arg:
 
-\\--log-base LOG_BASE [``colcon-core``]
+\--log-base LOG_BASE [``colcon-core``]
   The base path for all log directories.
   The default value is ``./log``.
   To completely disable logging, pass ``/dev/null`` (on POSIX) / ``nul`` (on
@@ -48,7 +48,7 @@ For each argument the name in brackets indicates which package contributes it.
 
 .. _colcon_log-level_arg:
 
-\\--log-level LOG_LEVEL [``colcon-core``]
+\--log-level LOG_LEVEL [``colcon-core``]
   Set the log level for the console output.
   The log file ``<log-dir>/logger_all.log`` always contains messages of all
   levels.

reference/mixin-arguments.rst

@@ -8,13 +8,13 @@ The following arguments are provided by the ``colcon-mixin`` package:
 
 .. _mixin-args_mixin-files_arg:
 
-\\--mixin-files [FILE [FILE ...]]
+\--mixin-files [FILE [FILE ...]]
   Read additional mixin files and make the mixin names specified in them
   available in the ``--mixin`` argument.
 
 .. _mixin-args_mixin_arg:
 
-\\--mixin [mixin1 [mixin2 ...]]
+\--mixin [mixin1 [mixin2 ...]]
   The names of mixins to be used.
   The list of mixin names and their command line arguments depends on which
   ones are available.

reference/package-selection-arguments.rst

@@ -9,7 +9,7 @@ For each argument the name in brackets indicates which package contributes it.
 
 .. _package-selection-args_build-base_arg:
 
-\\--build-base BUILD_BASE
+\--build-base BUILD_BASE
   The base path for all build directories.
   The default value is ``./build``.
   Each package uses a subdirectory in that base path as its package specific
@@ -21,101 +21,101 @@ For each argument the name in brackets indicates which package contributes it.
 
 .. _package-selection-args_packages-up-to_arg:
 
-\\--packages-up-to [PKG_NAME [PKG_NAME ...]]
+\--packages-up-to [PKG_NAME [PKG_NAME ...]]
   Select the packages with the passed names as well as their recursive
   dependencies.
 
 .. _package-selection-args_packages-up-to-regex_arg:
 
-\\--packages-up-to-regex [PATTERN [PATTERN ...]]
+\--packages-up-to-regex [PATTERN [PATTERN ...]]
   Select the packages that match any of the passed patterns as well as their
   recursive dependencies.
 
 .. _package-selection-args_packages-above_arg:
 
-\\--packages-above [PKG_NAME [PKG_NAME ...]]
+\--packages-above [PKG_NAME [PKG_NAME ...]]
   Select the packages with the passed names as well as packages which
   recursively depend on them.
 
 .. _package-selection-args_packages-above-and-dependencies_arg:
 
-\\--packages-above-and-dependencies [PKG_NAME [PKG_NAME ...]]
+\--packages-above-and-dependencies [PKG_NAME [PKG_NAME ...]]
   Select the packages with the passed names, packages which
   recursively depend on them as well as their recursive dependencies.
 
 .. _package-selection-args_packages-above-depth_arg:
 
-\\--packages-above-depth DEPTH [PKG_NAME ...]
+\--packages-above-depth DEPTH [PKG_NAME ...]
   Select the packages with the passed names as well as packages which
   recursively depend on them up to the given depth.
 
 .. _package-selection-args_packages-by-dep_arg:
 
-\\--packages-select-by-dep [DEP_NAME [DEP_NAME ...]]
+\--packages-select-by-dep [DEP_NAME [DEP_NAME ...]]
   Select packages which (recursively) depend on the given packages.
 
 .. _package-selection-args_packages-skip-by-dep_arg:
 
-\\--packages-skip-by-dep [DEP_NAME [DEP_NAME ...]]
+\--packages-skip-by-dep [DEP_NAME [DEP_NAME ...]]
   Skip packages which (recursively) depend on the given packages.
 
 .. _package-selection-args_packages-skip-up-to_arg:
 
-\\--packages-skip-up-to [PKG_NAME [PKG_NAME ...]]
+\--packages-skip-up-to [PKG_NAME [PKG_NAME ...]]
   Skip the packages with the passed names as well as their recursive
   dependencies.
 
 .. _package-selection-args_packages-select-build-failed_arg:
 
-\\--packages-select-build-failed
+\--packages-select-build-failed
   Select packages which have failed to build previously.
   Packages which have been aborted previously are not included.
 
 .. _package-selection-args_packages-skip-build-finished_arg:
 
-\\--packages-skip-build-finished
+\--packages-skip-build-finished
   Skip packages which have finished to build previously.
 
 .. _package-selection-args_packages-select-test-failures_arg:
 
-\\--packages-select-test-failures
+\--packages-select-test-failures
   Select packages which had test failures previously.
 
 .. _package-selection-args_packages-skip-test-passed_arg:
 
-\\--packages-skip-test-passed
+\--packages-skip-test-passed
   Skip packages which had no test failures previously.
 
 .. _package-selection-args_packages-select_arg:
 
-\\--packages-select [PKG_NAME [PKG_NAME ...]]
+\--packages-select [PKG_NAME [PKG_NAME ...]]
   Select the packages with the passed names.
 
 .. _package-selection-args_packages-skip_arg:
 
-\\--packages-skip [PKG_NAME [PKG_NAME ...]]
+\--packages-skip [PKG_NAME [PKG_NAME ...]]
   Skip the packages with the passed names.
 
 .. _package-selection-args_packages-select-regex_arg:
 
-\\--packages-select-regex [PATTERN [PATTERN ...]]
+\--packages-select-regex [PATTERN [PATTERN ...]]
   Select the packages where any of the patterns match the package name.
 
 .. _package-selection-args_packages-skip-regex_arg:
 
-\\--packages-skip-regex [PATTERN [PATTERN ...]]
+\--packages-skip-regex [PATTERN [PATTERN ...]]
   Skip the packages where any of the patterns match the package name.
 
 .. _package-selection-args_packages-start_arg:
 
-\\--packages-start PKG_NAME
+\--packages-start PKG_NAME
   Skip packages before the given package name in flat topological ordering.
   This option only makes sense when using the
   :ref:`sequential executor <executor-args_executor_arg_sequential>`.
 
 .. _package-selection-args_packages-end_arg:
 
-\\--packages-end PKG_NAME
+\--packages-end PKG_NAME
   Skip packages after the given package name in flat topological ordering.
   This option only makes sense when using the
   :ref:`sequential executor <executor-args_executor_arg_sequential>`.