Skip to content

Commit

Permalink
Improve Sphinx Infrastructure
Browse files Browse the repository at this point in the history 
- Mandate Python >=3.10 across the repo (Not really enforced)
  - Older versions are not tested and Python isn't required for OpenDDS
    users. This is also the version in the last Ubuntu LTS release.
- Require Sphinx >=7.2
  - Mostly for some minor API improvements, but since `build.py` will
    automatically download it, there's not much of a reason to hold it
    back.
- Try removing workaround for a RTD error.
- Workaround "LaTeX Error: Too deeply nested." on local PDF builds.
- Sphinx CMake domain:
  - Refactor to use a reusable custom domain framework
  - Add examples for all the directives and roles.
  - Rename `:nocontententry:` and other options for Sphinx 7.
  • Loading branch information
@iguessthislldo
iguessthislldo committed Feb 1, 2024
1 parent 3055313 commit 9260596
Show file tree
Hide file tree
Showing 8 changed files with 566 additions and 339 deletions.
17 changes: 16 additions & 1 deletion docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ def setup(app):
extensions = [
# Custom ones
'links',
'cmake',
'cmake_domain',

# Official ones
'sphinx.ext.ifconfig',
Expand Down Expand Up @@ -214,4 +214,19 @@ def setup(app):

latex_logo = 'logo_276_186.png'

latex_elements = {
# This seems to fix "LaTeX Error: Too deeply nested." on local PDF builds
# https://stackoverflow.com/questions/57945414
'preamble': r'''
\usepackage{enumitem}
\setlistdepth{20}
\renewlist{itemize}{itemize}{20}
\renewlist{enumerate}{enumerate}{20}
\setlist[itemize]{label=$\cdot$}
\setlist[itemize,1]{label=\textbullet}
\setlist[itemize,2]{label=--}
\setlist[itemize,3]{label=*}
''',
}

# vim: expandtab:ts=4:sw=4
104 changes: 52 additions & 52 deletions docs/devguide/building/cmake.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -285,50 +285,50 @@ The CMake package can provide library targets that can be linked using `target_l
.. versionadded:: 3.25

.. cmake:tgt:: ACE::ACE
:nocontentsentry:
:no-contents-entry:

Required

.. cmake:tgt:: ACE::XML_Utils
:nocontentsentry:
:no-contents-entry:

.. cmake:tgt:: TAO::TAO
:nocontentsentry:
:no-contents-entry:

Required

.. cmake:tgt:: TAO::IDL_FE
:nocontentsentry:
:no-contents-entry:

.. cmake:tgt:: TAO::AnyTypeCode
:nocontentsentry:
:no-contents-entry:

.. cmake:tgt:: TAO::BiDirGIOP
:nocontentsentry:
:no-contents-entry:

.. cmake:tgt:: TAO::CodecFactory
:nocontentsentry:
:no-contents-entry:

.. cmake:tgt:: TAO::IORManip
:nocontentsentry:
:no-contents-entry:

.. cmake:tgt:: TAO::IORTable
:nocontentsentry:
:no-contents-entry:

.. cmake:tgt:: TAO::ImR_Client
:nocontentsentry:
:no-contents-entry:

.. cmake:tgt:: TAO::PI
:nocontentsentry:
:no-contents-entry:

.. cmake:tgt:: TAO::PortableServer
:nocontentsentry:
:no-contents-entry:

.. cmake:tgt:: TAO::Svc_Utils
:nocontentsentry:
:no-contents-entry:

.. cmake:tgt:: TAO::Valuetype
:nocontentsentry:
:no-contents-entry:

.. _cmake-executables:

Expand Down Expand Up @@ -477,7 +477,7 @@ Functions
After ``opendds_target_sources`` is run on a target, it will have these target properties set on it:

.. cmake:prop:: OPENDDS_LANGUAGE_MAPPINGS
:nocontentsentry:
:no-contents-entry:

This holds the IDL language mappings used in the target based on what is passed to :cmake:func:`opendds_target_sources(OPENDDS_IDL_OPTIONS)`.

Expand Down Expand Up @@ -506,7 +506,7 @@ Functions
.. _cmake-files-props:

.. cmake:prop:: OPENDDS_GENERATED_DIRECTORY
:nocontentsentry:
:no-contents-entry:

The is the directory where generated files have been placed.
This is an absolute path and is not exported with the target.
Expand All @@ -524,40 +524,40 @@ Functions
- These properties are not exported with the target because the paths may not be valid any more if the build directory has been removed or the export is being used on another machine.

.. cmake:prop:: OPENDDS_PASSED_IDL_INTERFACE_FILES
:nocontentsentry:
:no-contents-entry:

The ``PUBLIC`` and ``INTERFACE`` scoped IDL files passed.

.. versionadded:: 3.20

.. cmake:prop:: OPENDDS_GENERATED_IDL_INTERFACE_FILES
:nocontentsentry:
:no-contents-entry:

The IDL files generated from the IDL files in :cmake:prop:`OPENDDS_PASSED_IDL_INTERFACE_FILES`.

.. versionadded:: 3.20

.. cmake:prop:: OPENDDS_ALL_IDL_INTERFACE_FILES
:nocontentsentry:
:no-contents-entry:

Combination of :cmake:prop:`OPENDDS_PASSED_IDL_INTERFACE_FILES` and :cmake:prop:`OPENDDS_GENERATED_IDL_INTERFACE_FILES`.

.. cmake:prop:: OPENDDS_GENERATED_HEADER_FILES
:nocontentsentry:
:no-contents-entry:

The ``.h`` and ``.inl`` files generated from :cmake:prop:`OPENDDS_ALL_IDL_INTERFACE_FILES`.

.. versionadded:: 3.20

.. cmake:prop:: OPENDDS_ALL_GENERATED_INTERFACE_FILES
:nocontentsentry:
:no-contents-entry:

Combination of :cmake:prop:`OPENDDS_GENERATED_IDL_INTERFACE_FILES` and :cmake:prop:`OPENDDS_GENERATED_HEADER_FILES`.

.. versionadded:: 3.20

.. cmake:prop:: OPENDDS_ALL_INTERFACE_FILES
:nocontentsentry:
:no-contents-entry:

All the ``INTERFACE`` and ``PUBLIC`` scoped files that were passed in or generated.

Expand Down Expand Up @@ -748,56 +748,56 @@ Dependencies
^^^^^^^^^^^^

.. cmake:var:: OPENDDS_ACE
:nocontentsentry:
:no-contents-entry:

Path to :ref:`deps-ace`, usually :envvar:`ACE_ROOT`

.. cmake:var:: OPENDDS_ACE_VERSION
:nocontentsentry:
:no-contents-entry:

The version of ACE being used.

.. versionadded:: 3.27

.. cmake:var:: OPENDDS_TAO
:nocontentsentry:
:no-contents-entry:

Path to :ref:`deps-tao`, usually :envvar:`TAO_ROOT`

.. cmake:var:: OPENDDS_TAO_VERSION
:nocontentsentry:
:no-contents-entry:

The version of TAO being used.

.. versionadded:: 3.27

.. cmake:var:: OPENDDS_OPENSSL
:nocontentsentry:
:no-contents-entry:

Path to :ref:`deps-openssl`

.. cmake:var:: OPENDDS_GTEST
:nocontentsentry:
:no-contents-entry:

Path to :ref:`deps-gtest`

.. cmake:var:: OPENDDS_JAVA
:nocontentsentry:
:no-contents-entry:

Path to :ref:`deps-java`

.. cmake:var:: OPENDDS_QT
:nocontentsentry:
:no-contents-entry:

Path to :ref:`deps-qt`

.. cmake:var:: OPENDDS_RAPIDJSON
:nocontentsentry:
:no-contents-entry:

Path to :ref:`deps-rapidjson`

.. cmake:var:: OPENDDS_XERCES3
:nocontentsentry:
:no-contents-entry:

Path to :ref:`deps-xerces`

Expand All @@ -820,111 +820,111 @@ Features
^^^^^^^^

.. cmake:var:: OPENDDS_CXX11
:nocontentsentry:
:no-contents-entry:

ACE/TAO and OpenDDS were built with C++11 or later.
Default depends on the compiler being used.
Has no effect when building OpenDDS using CMake.

.. cmake:var:: OPENDDS_DEBUG
:nocontentsentry:
:no-contents-entry:

Default depends on `CMAKE_BUILD_TYPE <https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html>`__.
When building OpenDDS using CMake ``CMAKE_BUILD_TYPE`` should be used.

.. cmake:var:: OPENDDS_OPTIMIZE
:nocontentsentry:
:no-contents-entry:

Default depends on `CMAKE_BUILD_TYPE <https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html>`__.
When building OpenDDS using CMake ``CMAKE_BUILD_TYPE`` should be used.

.. cmake:var:: OPENDDS_INLINE
:nocontentsentry:
:no-contents-entry:

``.inl`` files are included in header files.
Default is ``ON``
Has no effect when building OpenDDS using CMake.

.. cmake:var:: OPENDDS_VERSIONED_NAMEPSACE
:nocontentsentry:
:no-contents-entry:

ACE/TAO and OpenDDS have versioned namespaces.
Default is ``OFF``

.. cmake:var:: OPENDDS_STATIC
:nocontentsentry:
:no-contents-entry:

ACE/TAO are built as static libraries.
Default depends on `BUILD_SHARED_LIBS <https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html>`__.
When building OpenDDS using CMake ``BUILD_SHARED_LIBS`` should be used.

.. cmake:var:: OPENDDS_WCHAR
:nocontentsentry:
:no-contents-entry:

ACE/TAO prefers using wide characters.
Default is ``OFF``

.. cmake:var:: OPENDDS_TAO_IIOP
:nocontentsentry:
:no-contents-entry:

Default is ``ON``

.. cmake:var:: OPENDDS_TAO_OPTIMIZE_COLLOCATED_INVOCATIONS
:nocontentsentry:
:no-contents-entry:

Default is ``ON``

.. cmake:var:: OPENDDS_BUILT_IN_TOPICS
:nocontentsentry:
:no-contents-entry:

Default is ``ON``

.. cmake:var:: OPENDDS_OBJECT_MODEL_PROFILE
:nocontentsentry:
:no-contents-entry:

Default is ``ON``

.. cmake:var:: OPENDDS_PERSISTENCE_PROFILE
:nocontentsentry:
:no-contents-entry:

Default is ``ON``

.. cmake:var:: OPENDDS_OWNERSHIP_PROFILE
:nocontentsentry:
:no-contents-entry:

Default is ``ON``

.. cmake:var:: OPENDDS_OWNERSHIP_KIND_EXCLUSIVE
:nocontentsentry:
:no-contents-entry:

Default is the value of :cmake:var:`OPENDDS_OWNERSHIP_PROFILE`.

.. cmake:var:: OPENDDS_CONTENT_SUBSCRIPTION
:nocontentsentry:
:no-contents-entry:

Default is ``ON``

.. cmake:var:: OPENDDS_CONTENT_FILTERED_TOPIC
:nocontentsentry:
:no-contents-entry:

Default is the value of :cmake:var:`OPENDDS_CONTENT_SUBSCRIPTION`.

.. cmake:var:: OPENDDS_MULTI_TOPIC
:nocontentsentry:
:no-contents-entry:

Default is the value of :cmake:var:`OPENDDS_CONTENT_SUBSCRIPTION`.

.. cmake:var:: OPENDDS_QUERY_CONDITION
:nocontentsentry:
:no-contents-entry:

Default is the value of :cmake:var:`OPENDDS_CONTENT_SUBSCRIPTION`.

.. cmake:var:: OPENDDS_SECURITY
:nocontentsentry:
:no-contents-entry:

Default is ``OFF``

.. cmake:var:: OPENDDS_SAFETY_PROFILE
:nocontentsentry:
:no-contents-entry:

Default is ``OFF``
2 changes: 1 addition & 1 deletion docs/devguide/building/dependencies.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -220,7 +220,7 @@ Python
`Python <https://www.python.org/>`__ is used for some scripts where Perl isn't as suitable.
Most notably this includes :doc:`this Sphinx-based documentation </internal/docs>` and processing the results of the CMake tests in :ghfile:`tests/auto_run_tests.pl` if ``--cmake`` is passed.

Unless noted otherwise, Python should be version 3.6 or later.
Unless noted otherwise, Python should be version 3.10 or later.

Because it's an optional dependency, Python should not be required for any script used for building and testing the core functionality of OpenDDS.
Right now only Perl can be used for situations like that.
Loading

0 comments on commit 9260596

Please sign in to comment.