Merge pull request OpenDDS#4467 from iguessthislldo/igtd/config-sphin…

…x-domain

Add Config Sphinx Domain, Make Use of It in `[common]` Config Section, Add More Info About Plugins

NEWS.md

@@ -29,9 +29,9 @@ Read [the documentation for this release on Read the Docs](https://opendds.readt
 ### Fixes
 
 - Updated the [read](https://opendds.readthedocs.io/en/dds-3.27/devguide/xtypes.html#xtypes-interpreting-data-samples-with-dynamicdata) and [write](https://opendds.readthedocs.io/en/dds-3.27/devguide/xtypes.html#xtypes-populating-data-samples-with-dynamicdata) semantics of DynamicData for union, expandable collections (sequence and string), and optional member of an aggregated type. ([PR #4278](https://github.com/OpenDDS/OpenDDS/pull/4278))
-- Fixed memory leak where instances were not cleaned up with exlusive ownership. ([PR #4343](https://github.com/OpenDDS/OpenDDS/pull/4343))
+- Fixed memory leak where instances were not cleaned up with exclusive ownership. ([PR #4343](https://github.com/OpenDDS/OpenDDS/pull/4343))
 - Removed the special handling for sequence members with length code of 5,6, or 7. ([PR #4376](https://github.com/OpenDDS/OpenDDS/pull/4376))
-- Reading data from a dynamic data object for a primitive type now must use MEMBER_ID_INVALID id. ([PR #4376](https://github.com/OpenDDS/OpenDDS/pull/4376))
+- Reading data from a dynamic data object for a primitive type now must use `MEMBER_ID_INVALID` id. ([PR #4376](https://github.com/OpenDDS/OpenDDS/pull/4376))
 - `create_datawriter` and `create_datareader` check if the topic belongs to the same participant as the publisher/subscriber. ([PR #4398](https://github.com/OpenDDS/OpenDDS/pull/4398))
 - Fixed uninitialized `durability_service` in Topic QoS when using QoS-XML. ([PR #4424](https://github.com/OpenDDS/OpenDDS/pull/4424))
 - Fixed a bug where compiling IDL with `-Lc++11 -Gequality` produced code outside of a namespace that didn't compile. ([PR #4450](https://github.com/OpenDDS/OpenDDS/pull/4450))
@@ -105,7 +105,7 @@ Read [the documentation for this release on Read the Docs](https://opendds.readt
 
 ### Documentation
 
-* Remove -Grapidjson flag [opendds_idl] ([PR #4231](https://github.com/OpenDDS/OpenDDS/pull/4231))
+* Removed documentation for `-Grapidjson` option of `opendds_idl` that was removed in 3.20.0 ([PR #4231](https://github.com/OpenDDS/OpenDDS/pull/4231))
 * Remove reference to mailing lists ([PR #4234](https://github.com/OpenDDS/OpenDDS/pull/4234))
 * Restructured parts of [DDS Security](https://opendds.readthedocs.io/en/dds-3.26/devguide/dds_security.html#dds-security) page and expanded documentation of some XML security document elements. ([PR #4281](https://github.com/OpenDDS/OpenDDS/pull/4281))
 * OS-specific instructions will now be automatically selected based on the browser's user agent. ([PR #4281](https://github.com/OpenDDS/OpenDDS/pull/4281))

docs/build.py

@@ -31,7 +31,8 @@ def log(*args, **kwargs):
 
 
 class DocEnv:
-    def __init__(self, venv_path, build_path, gh_links_commit=None, conf_defines=None):
+    def __init__(self, venv_path, build_path,
+            gh_links_commit=None, conf_defines=None, debug=False):
         self.venv_path = Path(venv_path)
         self.abs_venv_path = self.venv_path.resolve()
         self.bin_path = self.abs_venv_path / 'bin'
@@ -42,6 +43,7 @@ def __init__(self, venv_path, build_path, gh_links_commit=None, conf_defines=Non
             self.conf_defines.extend(conf_defines)
         if gh_links_commit is not None:
             self.conf_defines.append('github_links_commitish=' + gh_links_commit)
+        self.debug = debug
         self.done = set()
 
     def run(self, *cmd, cwd=abs_docs_path):
@@ -82,6 +84,8 @@ def sphinx_build(self, builder, *args):
         args = list(args)
         for define in self.conf_defines:
             args.append('-D' + define)
+        if self.debug:
+            args.append('-vv')
         self.run('sphinx-build', '-M', builder, '.', str(self.abs_build_path), *args)
 
     def do(self, actions, because_of=None, open_result=False):
@@ -104,7 +108,15 @@ def do(self, actions, because_of=None, open_result=False):
     def all_actions(cls):
         return [k[3:] for k, v in vars(cls).items() if k.startswith('do_')]
 
+    def do_test(self):
+        self.run('python3', '-m', 'unittest', 'discover', '--verbose',
+            '--start-directory', 'sphinx_extensions',
+            '--pattern', '*.py',
+            cwd=abs_docs_path)
+        return None
+
     def do_strict(self):
+        self.do(['test'], because_of='strict')
         self.sphinx_build('dummy', '-W')
         self.sphinx_build('linkcheck')
         return None
@@ -162,12 +174,14 @@ def do_markdown(self):
         action='append',
         help='Passed to sphinx-build to override conf.py values.'
     )
+    arg_parser.add_argument('-d', '--debug', action='store_true')
     args = arg_parser.parse_args()
 
     doc_env = DocEnv(
         venv_path=args.venv, build_path=args.build,
         gh_links_commit=args.gh_links_commit,
         conf_defines=args.conf_defines,
+        debug=args.debug,
     )
     doc_env.setup()
     doc_env.do(args.actions, open_result=args.open)

docs/conf.py

@@ -103,6 +103,7 @@ def setup(app):
     # Custom ones
     'links',
     'cmake_domain',
+    'config_domain',
 
     # Official ones
     'sphinx.ext.ifconfig',

docs/devguide/alternate_interfaces_to_data.rst

@@ -66,7 +66,7 @@ Usage Model
     Sect<12.1.2>
 
 The application creates any number of ``Recorder``\s and ``Replayer``\s as necessary.
-This could be based on using the Built-In Topics to dynamically discover which topics are active in the Domain.
+This could be based on using the :term:`built-in topics` to dynamically discover which topics are active in the Domain.
 Creating a ``Recorder`` or ``Replayer`` requires the application to provide a topic name and type name (as in ``DomainParticipant::create_topic()``) and also the relevant QoS data structures.
 The ``Recorder`` requires SubscriberQos and DataReaderQos whereas the ``Replayer`` requires PublisherQos and DataWriterQos.
 These values are used in discovery's reader/writer matching.
@@ -141,7 +141,7 @@ The properties can be divided into a few categories:
   * Durability Service
   * Ownership and Ownership Strength (still used for reader/writer match)
 
-* Affects reader/writer matching and Built-In Topics but otherwise ignored
+* Affects reader/writer matching and :term:`built-in topics` but otherwise ignored
 
   * Partition
   * Reliability (still used by transport negotiation)

docs/devguide/building/cmake.rst

@@ -248,35 +248,35 @@ The CMake package can provide library targets that can be linked using `target_l
 
 .. cmake:tgt:: OpenDDS::Rtps
 
-  :ref:`RTPS Discovery <introduction--peer-to-peer-discovery-with-rtps>`
+  :ref:`rtps-disc`
 
 .. cmake:tgt:: OpenDDS::InfoRepoDiscovery
 
-  :ref:`InfoRepo Discovery <introduction--centralized-discovery-with-dcpsinforepo>`
+  :ref:`inforepo-disc`
 
 .. cmake:tgt:: OpenDDS::Rtps_Udp
 
-  :ref:`RTPS/UDP Transport <run_time_configuration--rtps-udp-transport-configuration-options>`
+  :ref:`rtps-udp-transport`
 
 .. cmake:tgt:: OpenDDS::Multicast
 
-  :ref:`Multicast Transport <run_time_configuration--ip-multicast-transport-configuration-options>`
+  :ref:`multicast-transport`
 
 .. cmake:tgt:: OpenDDS::Shmem
 
-  :ref:`Shared Memory Transport <run_time_configuration--shared-memory-transport-configuration-options>`
+  :ref:`shmem-transport`
 
 .. cmake:tgt:: OpenDDS::Tcp
 
-  :ref:`TCP Transport <run_time_configuration--tcp-ip-transport-configuration-options>`
+  :ref:`tcp-transport`
 
 .. cmake:tgt:: OpenDDS::Udp
 
-  :ref:`UDP Transport <run_time_configuration--udp-ip-transport-configuration-options>`
+  :ref:`udp-transport`
 
 .. cmake:tgt:: OpenDDS::Security
 
-  :doc:`/devguide/dds_security`
+  :ref:`sec`
 
 .. cmake:tgt:: OpenDDS::RtpsRelayLib
 

docs/devguide/built_in_topics.rst

@@ -2,7 +2,7 @@
 .. _bit:
 
 ###############
-Built-In Topics
+Built-in Topics
 ###############
 
 ..
@@ -17,18 +17,17 @@ Introduction
 ..
     Sect<6.1>
 
-In OpenDDS, Built-In-Topics are created and published by default to exchange information about DDS participants operating in the deployment.
-When OpenDDS is used in a centralized discovery approach using the ``DCPSInfoRepo`` service, the Built-In-Topics are published by this service.
-For DDSI-RTPS discovery, the internal OpenDDS implementation instantiated in a process populates the caches of the Built-In Topic DataReaders.
-See :ref:`run_time_configuration--configuring-for-ddsi-rtps-discovery` for a description of RTPS discovery configuration.
+In OpenDDS, built-in topics are created and published by default to exchange information about DDS participants operating in the deployment.
+When OpenDDS is :ref:`inforepo-disc`, the built-in topics are published by this service.
+For :ref:`rtps-disc`, the internal OpenDDS implementation instantiated in a process populates the caches of the built-In topic DataReaders.
 
-The IDL struct ``BuiltinTopicKey_t`` is used by the Built-In Topics.
+The IDL struct ``BuiltinTopicKey_t`` is used by the built-in topics.
 This structure contains an array of 16 octets (bytes) which corresponds to an InfoRepo identifier or a DDSI-RTPS GUID.
 
 .. _built_in_topics--built-in-topics-for-dcpsinforepo-configuration:
 
 **********************************************
-Built-In Topics for DCPSInfoRepo Configuration
+Built-in Topics for DCPSInfoRepo Configuration
 **********************************************
 
 ..
@@ -40,15 +39,15 @@ Four separate topics are defined for each domain.
 Each is dedicated to a particular entity (domain participant :ref:`built_in_topics--dcpsparticipant-topic`, topic :ref:`built_in_topics--dcpsparticipant-topic`, data writer :ref:`built_in_topics--dcpspublication-topic`, data reader :ref:`built_in_topics--dcpssubscription-topic`) and publishes instances describing the state for each entity in the domain.
 
 Subscriptions to built-in topics are automatically created for each domain participant.
-A participant's support for Built-In-Topics can be toggled via the ``DCPSBit`` configuration option (see the table in :ref:`run_time_configuration--common-configuration-options`).
+A participant's support for built-in topics can be toggled via the :cfg:key:`DCPSBit` configuration option.
 To view the built-in topic data, simply obtain the built-in Subscriber and then use it to access the Data Reader for the built-in topic of interest.
 The Data Reader can then be used like any other Data Reader.
 
 See :ref:`built_in_topics--built-in-topic-subscription-example` for an example showing how to read from a built-in topic.
 
-If you are not planning on using Built-in-Topics in your application, you can configure OpenDDS to remove Built-In-Topic support at build time.
+If you are not planning on using built-in topics in your application, you can configure OpenDDS to remove built-in topic support at build time.
 Doing so can reduce the footprint of the core DDS library by up to 30%.
-See :ref:`building--disabling-the-building-of-built-in-topic-support` for information on disabling Built-In-Topic support.
+See :ref:`building--disabling-the-building-of-built-in-topic-support` for information on disabling built-in topic support.
 
 .. _built_in_topics--dcpsparticipant-topic:
 
@@ -80,7 +79,7 @@ DCPSTopic Topic
 ..
     Sect<6.4>
 
-.. note:: OpenDDS does not support this Built-In-Topic when configured for RTPS discovery.
+.. note:: OpenDDS does not support this built-in topic when configured for :ref:`rtps-disc`.
 
 The ``DCPSTopic`` topic publishes information about the topics in the domain.
 Here is the IDL that defines the structure published for this topic:
@@ -183,7 +182,7 @@ The fields above identify the Domain Participant (via its key) that the Data Rea
 .. _built_in_topics--built-in-topic-subscription-example:
 
 ***********************************
-Built-In Topic Subscription Example
+Built-in Topic Subscription Example
 ***********************************
 
 ..
@@ -214,7 +213,7 @@ The code for the other built-in topics is similar.
 .. _built_in_topics--opendds-specific-built-in-topics:
 
 ********************************
-OpenDDS-specific Built-In Topics
+OpenDDS-specific Built-in Topics
 ********************************
 
 ..
@@ -228,7 +227,7 @@ OpenDDSParticipantLocation Topic
 ..
     Sect<6.8.1>
 
-The Built-In Topic "OpenDDSParticipantLocation" is published by the DDSI-RTPS discovery implementation to give applications visibility into the details of how each remote participant is connected over the network.
+The built-in topic ``OpenDDSParticipantLocation`` is published by the DDSI-RTPS discovery implementation to give applications visibility into the details of how each remote participant is connected over the network.
 If the RtpsRelay (:ref:`internet_enabled_rtps--the-rtpsrelay`) and/or IETF ICE (:ref:`internet_enabled_rtps--interactive-connectivity-establishment-ice-for-rtps`) are enabled, their usage is reflected in the OpenDDSParticipantLocation topic data.
 The topic type ParticipantLocationBuiltinTopicData is defined in :ghfile:`dds/OpenddsDcpsExt.idl` in the ``OpenDDS::DCPS`` module:
 
@@ -263,7 +262,7 @@ OpenDDSConnectionRecord Topic
 ..
     Sect<6.8.2>
 
-The Built-In Topic "OpenDDSConnectionRecord" is published by the DDSI-RTPS discovery implementation and RTPS_UDP transport implementation to give applications visibility into the details of a participant's connection to an RtpsRelay instance.
+The built-in topic ``OpenDDSConnectionRecord`` is published by the DDSI-RTPS discovery implementation and RTPS_UDP transport implementation to give applications visibility into the details of a participant's connection to an RtpsRelay instance.
 Security must be enabled in the build of OpenDDS (:ref:`dds_security--building-opendds-with-security-enabled`) to use this topic.
 
 The topic type ConnectionRecord is defined in :ghfile:`dds/OpenddsDcpsExt.idl` in the ``OpenDDS::DCPS`` module:
@@ -286,13 +285,12 @@ OpenDDSInternalThread Topic
 ..
     Sect<6.8.3>
 
-The Built-In Topic "OpenDDSInternalThread" is published by the DDSI-RTPS discovery implementation when OpenDDS is configured with DCPSThreadStatusInterval (:ref:`run_time_configuration--common-configuration-options`).
-When enabled, the DataReader for this Built-In Topic will report the status of threads created and managed by OpenDDS within the current process.
+The built-in topic ``OpenDDSInternalThread`` is published when OpenDDS is configured with :cfg:key:`DCPSThreadStatusInterval`.
+When enabled, the DataReader for this built-in topic will report the status of threads created and managed by OpenDDS within the current process.
 The timestamp associated with samples can be used to determine the health (responsiveness) of the thread.
 
 The topic type InternalThreadBuiltinTopicData is defined in :ghfile:`dds/OpenddsDcpsExt.idl` in the ``OpenDDS::DCPS`` module:
 
 * ``thread_id`` (key) -- A string identifier for the thread.
 
 * ``utilization`` -- Estimated utilization of this thread (0.0-1.0).
-

docs/devguide/content_subscription_profile.rst

@@ -56,7 +56,7 @@ Creating a content-filtered topic requires the following parameters:
 
 * Filter expression
 
-  An SQL-like expression (:ref:`content_subscription_profile--filter-expressions`) which defines the subset of samples published on the related topic that should be received by the content-filtered topic's data readers.
+  An :ref:`SQL-like expression <content_subscription_profile--filter-expressions>` which defines the subset of samples published on the related topic that should be received by the content-filtered topic's data readers.
 
 * Expression parameters
 
@@ -68,11 +68,11 @@ Once the content-filtered topic has been created, it is used by the subscriber's
 This data reader is functionally equivalent to a normal data reader except that incoming data samples which do not meet the filter expression's criteria are dropped.
 
 Filter expressions are first evaluated at the publisher so that data samples which would be ignored by the subscriber can be dropped before even getting to the transport.
-This feature can be turned off with ``-DCPSPublisherContentFilter 0`` or the equivalent setting in the ``[common]`` section of the configuration file.
+This feature can be turned off by setting :cfg:key:`DCPSPublisherContentFilter` to ``0``.
 The behavior of non-default :ref:`qos-deadline` or :ref:`qos-liveliness` policies may be affected by this policy.
 Special consideration must be given to how the "missing" samples impact the QoS behavior, see the document in :ghfile:`docs/design/CONTENT_SUBSCRIPTION`.
 
-.. note:: RTPS_UDP transport does not always do Writer-side filtering.
+.. note:: :ref:`rtps-udp-transport` does not always do Writer-side filtering.
   It does not currently implement transport level filtering, but may be able to filter above the transport layer.
 
 .. _content_subscription_profile--filter-expressions:
@@ -83,9 +83,9 @@ Filter Expressions
 ..
     Sect<5.2.1>
 
-The formal grammar for filter expressions is defined in Annex A of the DDS specification.
+The formal grammar for filter expressions is defined in :omgspec:`dds:Annex B - Syntax for Queries and Filters`.
 This section provides an informal summary of that grammar.
-Query expressions (:ref:`content_subscription_profile--query-expressions`) and topic expressions (:ref:`content_subscription_profile--topic-expressions`) are also defined in Annex A.
+:ref:`Query expressions <content_subscription_profile--query-expressions>` and :ref:`topic expressions <content_subscription_profile--topic-expressions>` are also defined in the DDS specification.
 
 Filter expressions are combinations of one or more predicates.
 Each predicate is a logical expression taking one of two forms:
@@ -141,7 +141,7 @@ Filtering and Dispose/Unregister Samples
 ..
     Sect<5.2.3>
 
-DataReaders without filtering can see samples with the ``valid_data`` field of SampleInfo set to false.
+DataReaders without filtering can see samples with the ``valid_data`` field of ``SampleInfo`` set to ``false``.
 This happens when the matching DataWriter disposes or unregisters the instance.
 Content filtering (whether achieved through Content-Filtered Topics, Query Conditions, or Multi Topics) will filter such samples when the filter expression explicitly uses key fields.
 Filter expressions that don't meet that criteria will result in no such samples passing the filter.

docs/devguide/dds_security.rst

@@ -11,6 +11,16 @@ DDS Security
 OpenDDS includes an implementation of the :ref:`DDS Security specification <spec-dds-security>`.
 This allows participants to encrypt messages and to authenticate remote participants before engaging with them.
 
+.. important::
+
+  Library filename: ``OpenDDS_Security``
+
+  MPC base project name: :ghfile:`\`\`opendds_security\`\` <MPC/config/opendds_security.mpb>`
+
+  CMake target Name: :cmake:tgt:`OpenDDS::Security`
+
+  :ref:`Initialization header <plugins>`: :ghfile:`dds/DCPS/security/BuiltInPlugins.h`
+
 .. _dds_security--building-opendds-with-security-enabled:
 
 **************************************
@@ -140,7 +150,7 @@ The following configuration steps are required to enable OpenDDS Security featur
 
    * Via API: ``TheServiceParticipant->set_security(true);`` or
 
-   * Via config file: ``DCPSSecurity=1`` in the ``[common]`` section.
+   * Via config file: setting :cfg:key:`DCPSSecurity` to ``1``.
 
 .. _dds_security--dds-security-configuration-via-propertyqospolicy: