Improving docs (#523)

* Fix DeclareLaunchArgument reference in architecture.rst

Signed-off-by: Ivan Santiago Paunovic <[email protected]>

* Fixes in sphinx conf.py

Signed-off-by: Ivan Santiago Paunovic <[email protected]>

* Add python and xml examples in DeclareLaunchArgument.

Signed-off-by: Ivan Santiago Paunovic <[email protected]>

* Make pytest run doctests

Signed-off-by: Ivan Santiago Paunovic <[email protected]>

Author: ivanpauno

launch/conftest.py

@@ -0,0 +1,23 @@
+# Copyright 2021 Open Source Robotics Foundation, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def pytest_ignore_collect(path):
+    # pytest doctest messes up when trying to import .launch.py packages, ignore them.
+    # It also messes up when trying to import launch.logging.handlers due to conflicts with
+    # logging.handlers, ignore that as well.
+    return str(path).endswith((
+        '.launch.py',
+        'logging/handlers.py',
+    ))

launch/doc/source/architecture.rst

@@ -49,7 +49,7 @@ This is a non-exhaustive list of actions that `launch` may provide:
   - This action will set a :class:`launch.LaunchConfiguration` to a specified value, creating it if it doesn't already exist.
   - These launch configurations can be accessed by any action via a substitution, but are scoped by default.
 
-- :class:`launch.actions.DeclareLaunchDescriptionArgument`
+- :class:`launch.actions.DeclareLaunchArgument`
 
   - This action will declare a launch description argument, which can have a name, default value, and documentation.
   - The argument will be exposed via a command line option for a root launch description, or as action configurations to the include launch description action for the included launch description.

launch/doc/source/conf.py

@@ -64,6 +64,13 @@
     'sphinx.ext.githubpages',
 ]
 
+# autodoc settings
+autodoc_default_options = {
+    'special-members': '__init__',
+    'class-doc-from': 'class',
+}
+autodoc_class_signature = 'separated'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -108,7 +115,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

launch/launch/actions/conftest.py

@@ -0,0 +1,27 @@
+# Copyright 2021 Open Source Robotics Foundation, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# imports needed for doctests
+import launch
+import launch.actions
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def add_imports_to_doctest_namespace(doctest_namespace):
+    doctest_namespace['launch'] = launch
+    doctest_namespace['LaunchDescription'] = launch.LaunchDescription
+    for x in launch.actions.__all__:
+        doctest_namespace[x] = getattr(launch.actions, x)

launch/launch/actions/declare_launch_argument.py

@@ -74,6 +74,32 @@ class DeclareLaunchArgument(Action):
     exception is raised because none is set and there is no default value.
     However, the pre-condition does not guarantee that the argument was visible
     if behind condition or situational inclusions.
+
+    .. doctest::
+
+        >>> ld = LaunchDescription([
+        ...     DeclareLaunchArgument('simple_argument'),
+        ...     DeclareLaunchArgument('with_default_value', default_value='default'),
+        ...     DeclareLaunchArgument(
+        ...         'with_default_and_description',
+        ...         default_value='some_default',
+        ...         description='this argument is used to configure ...'),
+        ...     DeclareLaunchArgument(
+        ...         'mode',
+        ...         default_value='A',
+        ...         description='Choose between mode A and mode B',
+        ...         choices=['A', 'B']),
+        ...     # other actions here, ...
+        ... ])
+
+    .. code-block:: xml
+
+        <launch>
+            <arg name="simple_argument"/>
+            <arg name="with_default_value" default_value="default"/>
+            <arg name="with_default_and_description" default_value="some_default"
+                description="this argument is used to configure ..."/>
+        </launch>
     """
 
     def __init__(

launch/pytest.ini

@@ -1,2 +1,3 @@
 [pytest]
 junit_family=xunit2
+addopts = --doctest-modules