Add sphinx documentation (#340)

* First version of sphinx doc

* Add generated docs to index

* Add missing file

* URSim-Docker section

* Added package overview entry page

* Update MoveIt! instructions as in the main README

* update ur_robot_driver README links

.gitignore

@@ -8,3 +8,7 @@ install_manifest.txt
 .directory
 .vscode
 .moveit_ci/
+docs_output
+docs_build
+cross_reference
+ur_robot_driver/doc/generated

ur_bringup/CMakeLists.txt

@@ -7,4 +7,8 @@ install(DIRECTORY config launch
   DESTINATION share/${PROJECT_NAME}
 )
 
+install(PROGRAMS scripts/start_ursim.sh
+  DESTINATION lib/${PROJECT_NAME}
+)
+
 ament_package()

ur_bringup/scripts/start_ursim.sh

@@ -0,0 +1,124 @@
+#!/bin/bash
+
+# copyright 2022 Universal Robots A/S
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#    * Redistributions of source code must retain the above copyright
+#      notice, this list of conditions and the following disclaimer.
+#
+#    * Redistributions in binary form must reproduce the above copyright
+#      notice, this list of conditions and the following disclaimer in the
+#      documentation and/or other materials provided with the distribution.
+#
+#    * Neither the name of the {copyright_holder} nor the names of its
+#      contributors may be used to endorse or promote products derived from
+#      this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+PERSISTENT_BASE="${HOME}/.ursim"
+URCAP_VERSION="1.0.5"
+
+help()
+{
+  # Display Help
+  echo "Starts URSim inside a docker container"
+  echo
+  echo "Syntax: `basename "$0"` [-m|s|h]"
+  echo "options:"
+  echo "    -m <model>     Robot model. One of [ur3, ur3e, ur5, ur5e, ur10, ur10e, ur16e]. Defaults to ur5e."
+  echo "    -h             Print this Help."
+  echo
+}
+
+ROBOT_MODEL=UR5
+ROBOT_SERIES=e-series
+
+validate_model()
+{
+  case $ROBOT_MODEL in
+    ur3|ur5|ur10)
+      ROBOT_MODEL=${ROBOT_MODEL^^}
+      ROBOT_SERIES=cb3
+      ;;
+    ur3e|ur5e|ur10e|ur16e)
+      ROBOT_MODEL=${ROBOT_MODEL^^}
+      ROBOT_MODEL=$(echo ${ROBOT_MODEL:0:$((${#ROBOT_MODEL}-1))})
+      ROBOT_SERIES=e-series
+      ;;
+    *)
+      echo "Not a valid robot model: $ROBOT_MODEL"
+      exit
+      ;;
+  esac
+}
+
+
+while getopts ":hm:s:" option; do
+  case $option in
+    h) # display Help
+      help
+      exit;;
+    m) # robot model
+      ROBOT_MODEL=${OPTARG}
+      validate_model
+      ;;
+    \?) # invalid option
+      echo "Error: Invalid option"
+      help
+      exit;;
+  esac
+done
+
+URCAP_STORAGE="${PERSISTENT_BASE}/${ROBOT_SERIES}/urcaps"
+PROGRAM_STORAGE="${PERSISTENT_BASE}/${ROBOT_SERIES}/programs"
+
+# Create local storage for programs and URCaps
+mkdir -p "${URCAP_STORAGE}"
+mkdir -p "${PROGRAM_STORAGE}"
+
+# Download external_control URCap
+if [[ ! -f "${URCAP_STORAGE}/externalcontrol-${URCAP_VERSION}.jar" ]]; then
+  curl -L -o "${URCAP_STORAGE}/externalcontrol-${URCAP_VERSION}.jar" \
+    "https://github.com/UniversalRobots/Universal_Robots_ExternalControl_URCap/releases/download/v${URCAP_VERSION}/externalcontrol-${URCAP_VERSION}.jar"
+fi
+
+# Check whether network already exists
+docker network inspect ursim_net > /dev/null
+if [ $? -eq 0 ]; then
+  echo "ursim_net already exists"
+else
+  echo "Creating ursim_net"
+  docker network create --subnet=192.168.56.0/24 ursim_net
+fi
+
+# run docker container
+docker run --rm -d --net ursim_net --ip 192.168.56.101\
+  -v "${URCAP_STORAGE}":/urcaps \
+  -v "${PROGRAM_STORAGE}":/ursim/programs \
+  -e ROBOT_MODEL="${ROBOT_MODEL}" \
+  --name ursim \
+  universalrobots/ursim_${ROBOT_SERIES} || exit
+
+trap "echo killing; docker container kill ursim; exit" SIGINT SIGTERM
+
+echo "Docker URSim is running"
+printf "\nTo access Polyscope, open the following URL in a web browser.\n\thttp://192.168.56.101:6080/vnc.html\n\n"
+echo "To exit, press CTRL+C"
+
+while :
+do
+  sleep 1
+done

ur_robot_driver/README.md

@@ -5,8 +5,7 @@ repository and requires other packages from that repository. Also, see the [main
 README](../README.md) for information on how to install and startup this driver.
 
 ## ROS-API
-The ROS API is documented in a [standalone document](doc/ROS_INTERFACE.md). It is auto-generated
-using [catkin_doc](https://github.com/fzi-forschungszentrum-informatik/catkin_doc).
+The ROS API is documented in a [standalone document](doc/ROS_INTERFACE.md).
 
 ## Technical details
 The following image shows a very coarse overview of the driver's architecture.
@@ -23,9 +22,8 @@ available.
 
 To actually control the robot, a program node from the **External Control** URCap must be running on
 the robot interpreting commands sent from an external source. When this program is not running, no
-controllers moving the robot around will be available, which is handled by the
-[controller_stopper](../controller_stopper/README.md). Please see the [initial setup
-guide](../README.md) on how to install and start this on the robot.
+controllers moving the robot around will be available. Please see the [initial setup
+guide](doc/installation/robot_setup.rst) on how to install and start this on the robot.
 
 The URScript that will be running on the robot is requested by the **External Control** program node
 from the remote ROS PC. The robot *ur_control.launch* file has a parameter called `urscript_file` to
@@ -48,7 +46,7 @@ dashboard services.
 
 For using the **tool communication interface** on e-Series robots, a `socat` script is prepared to
 forward the robot's tool communication interface to a local device on the ROS PC. See [the tool
-communication setup guide](doc/setup_tool_communication.md) for details.
+communication setup guide](doc/setup_tool_communication.rst) for details.
 
 This driver is using [ROS-Control](https://wiki.ros.org/ros_control) for any control statements.
 Therefore, it can be used with all position-based controllers available in ROS-Control. However, we

ur_robot_driver/doc/ROS_INTERFACE.md

@@ -1,6 +1,6 @@
 **NOTE**: This documentation is obsolete and does not cover in full the current state of driver.
 
-# ur_robot_driver
+# ROS interface
 
 The new driver for Universal Robots UR3, UR5 and UR10 robots with CB3 controllers and the e-series.
 

ur_robot_driver/doc/conf.py

@@ -0,0 +1,175 @@
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "ur_robot_driver"
+copyright = "2022, Universal Robots A/S"
+author = "Felix Exner"
+
+# The short X.Y version
+version = ""
+# The full version, including alpha/beta/rc tags
+release = ""
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = [".rst", ".md"]
+
+# The master toctree document.
+master_doc = "index"
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "alabaster"
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# 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"]
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "ur_robot_driverdoc"
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (
+        master_doc,
+        "ur_robot_driver.tex",
+        "ur\\_robot\\_driver Documentation",
+        "Felix Exner",
+        "manual",
+    ),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [(master_doc, "ur_robot_driver", "ur_robot_driver Documentation", [author], 1)]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (
+        master_doc,
+        "ur_robot_driver",
+        "ur_robot_driver Documentation",
+        author,
+        "ur_robot_driver",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ["search.html"]