From 5cca82b070eedd4bc9ada6cafca9f830e1e7a42d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9verin=20Lemaignan?= Date: Thu, 4 Apr 2013 18:06:15 +0200 Subject: [PATCH] Added man pages for each of the morse subcommands --- CMakeLists.txt | 6 +++ doc/conf.py.in | 6 +++ doc/man/morse-add_man_page.rst | 35 +++++++++++++++ doc/man/morse-check_man_page.rst | 21 +++++++++ doc/man/morse-create_man_page.rst | 24 ++++++++++ doc/man/morse-edit_man_page.rst | 43 ++++++++++++++++++ doc/man/morse-rm_man_page.rst | 28 ++++++++++++ doc/man/morse-run_man_page.rst | 74 +++++++++++++++++++++++++++++++ doc/man/morse_man_page.rst | 65 ++++++++++++--------------- 9 files changed, 266 insertions(+), 36 deletions(-) create mode 100644 doc/man/morse-add_man_page.rst create mode 100644 doc/man/morse-check_man_page.rst create mode 100644 doc/man/morse-create_man_page.rst create mode 100644 doc/man/morse-edit_man_page.rst create mode 100644 doc/man/morse-rm_man_page.rst create mode 100644 doc/man/morse-run_man_page.rst diff --git a/CMakeLists.txt b/CMakeLists.txt index 4b4b62909..c53c3eabb 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -265,6 +265,12 @@ ELSE() ${SPHINX_MAN_OUTPUT} && ${GZIP} -f ${SPHINX_MAN_OUTPUT}/*.1) INSTALL(FILES ${SPHINX_MAN_OUTPUT}/morse.1.gz + ${SPHINX_MAN_OUTPUT}/morse-run.1.gz + ${SPHINX_MAN_OUTPUT}/morse-create.1.gz + ${SPHINX_MAN_OUTPUT}/morse-edit.1.gz + ${SPHINX_MAN_OUTPUT}/morse-check.1.gz + ${SPHINX_MAN_OUTPUT}/morse-add.1.gz + ${SPHINX_MAN_OUTPUT}/morse-rm.1.gz ${SPHINX_MAN_OUTPUT}/morseexec.1.gz ${SPHINX_MAN_OUTPUT}/multinode_server.1.gz DESTINATION ${CMAKE_INSTALL_PREFIX}/share/man/man1 diff --git a/doc/conf.py.in b/doc/conf.py.in index d2e63c438..e5104aa25 100644 --- a/doc/conf.py.in +++ b/doc/conf.py.in @@ -208,5 +208,11 @@ latex_documents = [ # List of man pages described by # (startdocname, name, description, authors, section) tuples man_pages = [("morse_man_page", "morse", "A robotics simulator based upon the Blender Game Engine", "", 1), + ("morse-run_man_page", "morse-run", "Runs a MORSE simulation", "", 1), + ("morse-edit_man_page", "morse-edit", "Loads a MORSE simulation for further edition", "", 1), + ("morse-create_man_page", "morse-create", "Creates a MORSE simulation environment", "", 1), + ("morse-check_man_page", "morse-check", "Checks the MORSE configuration", "", 1), + ("morse-add_man_page", "morse-add", "Adds a component to a MORSE simulation environment", "", 1), + ("morse-rm_man_page", "morse-rm", "Removes a MORSE simulation environment", "", 1), ("morseexec_man_page", "morseexec", "Run a Python script with the default scene", "", 1), ("multinode_server_man_page", "multinode_server", "Server program to synchronise several instances of MORSE", "", 1)] diff --git a/doc/man/morse-add_man_page.rst b/doc/man/morse-add_man_page.rst new file mode 100644 index 000000000..b9a356021 --- /dev/null +++ b/doc/man/morse-add_man_page.rst @@ -0,0 +1,35 @@ +:orphan: + +morse add manual page +===================== + +Synopsis +-------- + +**morse add** [-h] [-f] {robot,sensor,actuator} name env + +Description +----------- + +Adds templates for a new component (sensor, actuator, robot) +to an existing simulation environment. + +This component is meant to be a starting point for writing our own +custom components. + +Options +------- + +:{robot,sensor,actuator}: + the type of component you want to add. +:name: the name of the new component. +:env: the environment where to add. + +:-h, --help: show this help message and exit +:-f, --force: forces the creation (possibly overwriting files). + +Refer to :manpage:`morse(1)` for global MORSE options. + +See Also +-------- +:manpage:`morse(1)` diff --git a/doc/man/morse-check_man_page.rst b/doc/man/morse-check_man_page.rst new file mode 100644 index 000000000..456bd768b --- /dev/null +++ b/doc/man/morse-check_man_page.rst @@ -0,0 +1,21 @@ +:orphan: + +morse check manual page +======================= + +Synopsis +-------- + +**morse check** + +Description +----------- + +This command checks that your MORSE installation is correct. + +In particular, it verifies that the Blender version and the Python +version are supported. + +See Also +-------- +:manpage:`morse(1)` diff --git a/doc/man/morse-create_man_page.rst b/doc/man/morse-create_man_page.rst new file mode 100644 index 000000000..c9e4507db --- /dev/null +++ b/doc/man/morse-create_man_page.rst @@ -0,0 +1,24 @@ +:orphan: + +morse create manual page +======================== + +Synopsis +-------- + +**morse create** [-h] [-f] env + + +Options +------- + +:env: the name of the environment to create. + +:-h, --help: show this help message and exit +:-f, --force: forces the creation (possibly overwriting files). + +Refer to :manpage:`morse(1)` for global MORSE options. + +See Also +-------- +:manpage:`morse(1)` diff --git a/doc/man/morse-edit_man_page.rst b/doc/man/morse-edit_man_page.rst new file mode 100644 index 000000000..e12848975 --- /dev/null +++ b/doc/man/morse-edit_man_page.rst @@ -0,0 +1,43 @@ +:orphan: + +morse edit manual page +====================== + +Synopsis +-------- + +**morse edit** [-h] [-b BASE] [--name NAME] [-g GEOM] [env] [file] [pyoptions...] + +Description +----------- + +Open the given Blender scene or Python script in the Blender +interface for edition. The simulation can be started by +pressing P. + +Options +------- + +:env: the simulation environment to edit. +:file: the exact scene (.py or .blend) to edit (if 'env' is + given, within this environment). + See section FILE RESOLUTION of :manpage:`morse-run(1)` for details. +:pyoptions: optional parameters, passed to the Blender python + engine in sys.argv + +:-h, --help: show this help message and exit +:-b BASE, --base BASE: specify a Blender scene used as base to apply the + Python script. +:--name NAME: when running in multi-node mode, sets the name of this + node (defaults to either MORSE_NODE if defined or + current hostname). +:-g GEOM, --geometry GEOM: + sets the simulator window geometry. Expected format: + WxH or WxH+dx,dy to set an initial x,y delta (from + lower left corner). + +Refer to :manpage:`morse(1)` for global MORSE options. + +See Also +-------- +:manpage:`morse(1)` diff --git a/doc/man/morse-rm_man_page.rst b/doc/man/morse-rm_man_page.rst new file mode 100644 index 000000000..fd427cd62 --- /dev/null +++ b/doc/man/morse-rm_man_page.rst @@ -0,0 +1,28 @@ +:orphan: + +morse rm manual page +===================== + +Synopsis +-------- + +**morse rm** [-h] [-f] env + +Description +----------- + +Deletes an existing simulation environment. + +Options +------- + +:env: the environment to delete. + +:-h, --help: show this help message and exit +:-f, --force: silently delete. + +Refer to :manpage:`morse(1)` for global MORSE options. + +See Also +-------- +:manpage:`morse(1)` diff --git a/doc/man/morse-run_man_page.rst b/doc/man/morse-run_man_page.rst new file mode 100644 index 000000000..e9324de35 --- /dev/null +++ b/doc/man/morse-run_man_page.rst @@ -0,0 +1,74 @@ +:orphan: + +morse run manual page +===================== + +Synopsis +-------- + +**morse run** [-h] [--name NAME] [-g GEOM] [env] [file] [pyoptions...] + +Description +----------- + +Runs a simulation (must be a Python script) without loading +the Blender interface. + +Options +------- + +:env: + the simulation environment to run. +:file: + the exact scene (.py or .blend) to run (if 'env' is + given, within this environment). + See section FILE RESOLUTION below for details. + +:pyoptions: + optional parameters, passed to the Blender python + engine in sys.argv +:-h, --help: + show this help message and exit + +:--name NAME: + when running in multi-node mode, sets the name of this + node (defaults to either MORSE_NODE if defined or + current hostname). +:-g GEOM, --geometry GEOM: + sets the simulator window geometry. Expected format: + WxH or WxH+dx,dy to set an initial x,y delta (from + lower left corner). + +Refer to :manpage:`morse(1)` for global MORSE options. + +File Resolution +--------------- + +MORSE tries to figure out which simulation you want to open with the following strategy: + + +**If only one parameter *arg* is given:** + +- if *arg* is a configured simulation environment with prefix $ENVROOT: + - if *$ENVROOT/default.py* exists, launch it. + - else, if any file with an extension {.py|.blend} exists, launch the first + one (in alphanumerical order) + - else if a file called *arg* exists in the current directory, launch it. + - else, fail +- else check if a file called *arg* exists, and launch it (note that in that + case, *arg* can contain an absolute path or a path relative to the current + directory). + +**If two parameters *arg1* and *arg2* are given:** + +- if *arg1* is a configured simulation environment with prefix $ENVROOT: + - if *$ENVROOT/arg2* exists, launch it + - else, add $ENVROOT to MORSE environment, and if *arg2* exists, launch it (note + that *arg2* can contain an absolute path or a path relative to the current + directory) +- else fail + + +See Also +-------- +:manpage:`morse(1)` diff --git a/doc/man/morse_man_page.rst b/doc/man/morse_man_page.rst index 634de057e..71071016e 100644 --- a/doc/man/morse_man_page.rst +++ b/doc/man/morse_man_page.rst @@ -6,9 +6,7 @@ morse manual page Synopsis -------- -**morse** [-h] [-b BASE] [--name NAME] [-c] [--reverse-color] [-g GEOM] - [-v] {create,check,edit,run} [env] [scene] ... - +**morse** [-h] [-c] [--reverse-color] [-v] {create,rm,add,check,run,edit} ... Description ----------- @@ -25,52 +23,47 @@ programmed via Python scripts or inside of Blender itself. Currently supported middleware includes YARP, MOOS, ROS, Pocolibs, as well as a plain socket interface. +Options +------- + +These options apply to any MORSE command. + +:-c, --color: + Uses colors for MORSE output. The default color scheme is well + adapted to terminals with a dark background. +:--reverse-color: + Uses an alternate color theme for MORSE output, well adapted to + terminals with a bright background. +:-h, --help: + Displays information regarding the program use. +:--version: + Displays the version number. + + Commands -------- +See "man morse-" for a documentation of each commands. + +:add: + Adds templates for a new component (sensor, actuator, robot) + to an existing simulation environment. :check: Checks the environment is correctly setup to run morse. -:create env: + +:create: Creates a new simulation environment in the current directory. A template simulation scene is also created. The environment is added to 'sites' in ~/.morse/config -:edit [env] [scene]: +:edit: Open the given Blender scene or Python script in the Blender interface for edition. The simulation can be started by pressing P. - If only 'env' is set, open 'scene.py' (or the first .py or .blend - found if 'scene.py' does not exist) in the given environment. - If only [scene] is set, try to open this file in the current - directory. - If both are set, open the file 'scene' in the environment 'env'. -:run [env] [scene]: +:rm: + Deletes an existing simulation environment. +:run: Runs a simulation (must be a Python script) without loading the Blender interface. - See above for the meaning of the [env] and [scene] parameters. -:base blender_file: - When running in Edit mode, and assuming your passing a Builder API - Python script, you can optionally set a 'base' Blender file on - which the Python script is applied. This is convenient to quickly - change the simulated environment without touching the Python - script, for instance. -:name node_name: - When running in multi-node mode, sets the name of this - node. It defaults to current hostname. -:color: - Uses colors for MORSE output. The default color scheme is well - adapted to terminals with a dark background. -:reverse-color: - Uses an alternate color theme for MORSE output, well adapted to - terminals with a bright background. -:geometry WxH+dx,dy: - Sets the simulator window geometry. Expected format: either WxH - or WxH+dx,dy to set an initial x,y delta (from the lower left - corner). -:help: - Displays information regarding the program use. -:version: - Displays the version number. - Files -----