From 3ee9432b340bca907a0a1d17714c92ce8c8c7939 Mon Sep 17 00:00:00 2001 From: John Harwell Date: Sat, 10 Sep 2022 20:19:39 -0500 Subject: [PATCH] Update docs references as I move SIERRA to my personal github --- README.rst | 191 ++++++++++++++++---------------------- docs/conf.py | 12 +-- docs/src/matrix.rst | 2 +- docs/src/packages.rst | 2 +- docs/src/requirements.rst | 2 +- docs/src/trial.rst | 8 +- setup.py | 2 +- sierra/core/cmdline.py | 2 +- sierra/version.py | 2 +- 9 files changed, 98 insertions(+), 125 deletions(-) diff --git a/README.rst b/README.rst index c6f43e37..8114c15b 100755 --- a/README.rst +++ b/README.rst @@ -21,13 +21,13 @@ SIERRA (reSearch pIpEline for Reproducibility, Reusability, and Automation) .. image:: https://img.shields.io/badge/python-3.9-blue.svg :target: https://www.python.org/downloads/release/python-390/ -.. |ci-integration-master| image:: https://github.com/swarm-robotics/sierra/actions/workflows/integration-all.yml/badge.svg?branch=master -.. |ci-analysis-master| image:: https://github.com/swarm-robotics/sierra/actions/workflows/static-analysis.yml/badge.svg?branch=master -.. |ci-coverage-master| image:: https://coveralls.io/repos/github/swarm-robotics/sierra/badge.svg?branch=master +.. |ci-integration-master| image:: https://github.com/jharwell/sierra/actions/workflows/integration-all.yml/badge.svg?branch=master +.. |ci-analysis-master| image:: https://github.com/jharwell/sierra/actions/workflows/static-analysis.yml/badge.svg?branch=master +.. |ci-coverage-master| image:: https://coveralls.io/repos/github/jharwell/sierra/badge.svg?branch=master -.. |ci-integration-devel| image:: https://github.com/swarm-robotics/sierra/actions/workflows/integration-all.yml/badge.svg?branch=devel -.. |ci-analysis-devel| image:: https://github.com/swarm-robotics/sierra/actions/workflows/static-analysis.yml/badge.svg?branch=devel -.. |ci-coverage-devel| image:: https://coveralls.io/repos/github/swarm-robotics/sierra/badge.svg?branch=devel +.. |ci-integration-devel| image:: https://github.com/jharwell/sierra/actions/workflows/integration-all.yml/badge.svg?branch=devel +.. |ci-analysis-devel| image:: https://github.com/jharwell/sierra/actions/workflows/static-analysis.yml/badge.svg?branch=devel +.. |ci-coverage-devel| image:: https://coveralls.io/repos/github/jharwell/sierra/badge.svg?branch=devel .. |license| image:: https://img.shields.io/badge/License-GPLv3-blue.svg :target: https://www.gnu.org/licenses/gpl-3.0 @@ -35,11 +35,11 @@ SIERRA (reSearch pIpEline for Reproducibility, Reusability, and Automation) .. |doi| image:: https://zenodo.org/badge/125774567.svg :target: https://zenodo.org/badge/latestdoi/125774567 -.. |docs| image:: https://readthedocs.org/projects/swarm-robotics-sierra/badge/?version=master - :target: https://readthedocs.org/projects/swarm-robotics-sierra/master +.. |docs| image:: https://readthedocs.org/projects/sierra/badge/?version=master + :target: https://readthedocs.org/projects/sierra/master .. |maintenance| image:: https://img.shields.io/badge/Maintained%3F-yes-green.svg - :target: https://gitHub.com/swarm-robotics/sierra/graphs/commit-activity + :target: https://gitHub.com/jharwell/sierra/graphs/commit-activity :Usage: @@ -73,7 +73,7 @@ To install SIERRA (requires python 3.8+): pip3 install sierra-research To get started using SIERRA, see `getting started -`_. +`_. Want to cite SIERRA? See `Citing`_. @@ -82,7 +82,7 @@ Have an issue using SIERRA? See `Troubleshooting`_. What is SIERRA? =============== -.. figure:: https://raw.githubusercontent.com/swarm-robotics/sierra/master/docs/figures/architecture.png +.. figure:: https://raw.githubusercontent.com/jharwell/sierra/master/docs/figures/architecture.png SIERRA architecture, organized by pipeline stage. Stages are listed left to right, and an approximate joint architectural/functional stack is top to @@ -147,7 +147,7 @@ cases: If aspects of either use case sound familiar, then there is a strong chance SIERRA could help you! SIERRA is well documented--see the `SIERRA docs -`_ to get started. +`_ to get started. Use Case #1: Alice The Robotics Researcher ------------------------------------------ @@ -262,121 +262,45 @@ SIERRA Support Matrix ===================== SIERRA supports multiple `platforms -`_ -which researchers can write code to target. In SIERRA terminology, a platform is -a "thing" (usually a simulator or robot) that you want to write to code to run +`_ which +researchers can write code to target. In SIERRA terminology, a platform is a +"thing" (usually a simulator or robot) that you want to write to code to run on. Note that platform != OS, in SIERRA terminology. If a SIERRA platform runs on a given OS, then SIERRA supports doing so; if it does not, then SIERRA does not. For example, SIERRA does not support running ARGoS on windows, because ARGoS does not support windows. -If your desired platform is not listed, see the `plugin tutorials -`_ -for how to add it via a plugin. - -.. list-table:: - :header-rows: 1 - :widths: 50,50 - - * - Platform - - - Description - - * - `ARGoS `_ - - - Simulator for fast simulation of large swarms. Requires ARGoS >= - 3.0.0-beta59. - - * - `ROS1 `_ - - - Using ROS1 with the Gazebo simulator. Requires Gazebo >= 11.9.0, ROS1 - Noetic or later. - - * - `ROS1+Robot `_ - - - Using ROS1 with a real robot platform of your choice. ROS1 Noetic or - later is required. - SIERRA supports multiple execution environments for execution of experiments, such as `High Performance Computing (HPC) environments -`_ -and `real robots -`_. +`_ and `real +robots `_. Which execution environment experiments targeting a given platform is (somewhat) -independent of the platform itself (see below). If your desired execution -environment is not listed, see the `plugin tutorials -`_ -for how to add it via a plugin. - - -.. list-table:: - :header-rows: 1 - :widths: 50,50 - - * - Execution Environment - - - Description - - * - `SLURM `_ - - - An HPC cluster managed by the SLURM scheduler - - * - `Torque/MOAB `_ - - - An HPC cluster managed by the Torque/MOAB scheduler - - * - Adhoc - - - Miscellaneous collection of networked HPC compute nodes or random - servers; not managed by a scheduler - - * - HPC local - - - The SIERRA host machine,e.g., a researcher's laptop - - * - `Turtlebot3 `_ - - - Real turtlebot3 robots - - -SIERRA also supports multiple output formats for experimental outputs. If the -format for your experimental outputs is not listed, see the `tutorials -`_ -for how to add it via a plugin. SIERRA currently only supports XML experimental -inputs. - -.. list-table:: - :header-rows: 1 - :widths: 50,50 - - * - Experimental Output Format - - - Scope - - * - CSV file +independent of the platform itself (see below). - - Raw experimental outputs, transforming into heatmap images. - - * - PNG file - - - Stitching images together into videos. +SIERRA also supports multiple output formats for experimental outputs, as shown +below. SIERRA currently only supports XML experimental inputs. SIERRA supports (mostly) mix-and-match between platforms, execution environments, experiment input/output formats as shown in its support matrix -below. This is one of the most powerful features of SIERRA! +below. This is one of the most powerful features of SIERRA! If your desired +platform/execution environment is not listed, see the `plugin tutorials +`_ for how to add +it via a plugin. .. list-table:: :header-rows: 1 :widths: 25,25,25,25 * - Execution Environment + - Platform - Experimental Input Format - Experimental Output Format - * - SLURM + * - `SLURM `_: An HPC cluster + managed by the SLURM scheduler. - ARGoS, ROS1+Gazebo @@ -384,7 +308,9 @@ below. This is one of the most powerful features of SIERRA! - CSV, PNG - * - Torque/MOAB + * - `Torque/MOAB + `_: + An HPC cluster managed by the Torque/MOAB scheduler. - ARGoS, ROS1+Gazebo @@ -392,7 +318,9 @@ below. This is one of the most powerful features of SIERRA! - CSV, PNG - * - ADHOC + * - ADHOC: A miscellaneous collection of networked HPC compute nodes or + random servers; not managed by a scheduler. + - ARGoS, ROS1+Gazebo @@ -400,7 +328,7 @@ below. This is one of the most powerful features of SIERRA! - CSV, PNG - * - Local + * - Local: The SIERRA host machine,e.g., a researcher's laptop. - ARGoS, ROS1+Gazebo @@ -408,7 +336,9 @@ below. This is one of the most powerful features of SIERRA! - CSV, PNG - * - ROS1+Turtlebot3 + * - ROS1+Turtlebot3: `Turtlebot3 + `_ + robots with ROS1. - ROS1+Gazebo, ROS1+robot @@ -416,6 +346,49 @@ below. This is one of the most powerful features of SIERRA! - CSV, PNG +For more details about the platforms out experimental output formats, see below. + +.. list-table:: + :header-rows: 1 + :widths: 50,50 + + * - Platform + + - Description + + * - `ARGoS `_ + + - Simulator for fast simulation of large swarms. Requires ARGoS >= + 3.0.0-beta59. + + * - `ROS1 `_ + `Gazebo `_ + + - Using ROS1 with the Gazebo simulator. Requires Gazebo >= 11.9.0, ROS1 + Noetic or later. + + * - `ROS1+Robot `_ + + - Using ROS1 with a real robot platform of your choice. ROS1 Noetic or + later is required. + + +.. list-table:: + :header-rows: 1 + :widths: 50,50 + + * - Experimental Output Format + + - Scope + + * - CSV file + + - Raw experimental outputs, transforming into heatmap images. + + * - PNG file + + - Stitching images together into videos. + + Requirements To Use SIERRA ========================== @@ -437,7 +410,7 @@ The basic requirements are: For more details, including the requirements for researcher code, see the `SIERRA requirements -`_. +`_. Citing ====== @@ -467,5 +440,5 @@ Contributing I welcome all types of contributions, no matter how large or how small, and if you have an idea, I'm happy to talk about it at any point :-). See `here -`_ +`_ for the general procedure. diff --git a/docs/conf.py b/docs/conf.py index 1843d3c5..f3ffa7e3 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -160,12 +160,12 @@ "https://www.cs.unm.edu/~wjust/CS523/S2018/Readings/Hecker_Beyond_Pheromones_Swarm_Intelligence.pdf"), "Rosenfeld2006": ("Rosenfeld2006", "http://users.umiacs.umd.edu/~sarit/data/articles/rosenfeldetalbook06.pdf"), - "SIERRA_GITHUB": ("https://github.com:swarm-robotics/sierra.git", - "https://github.com:swarm-robotics/sierra.git"), - "SIERRA_SAMPLE_PROJECT": ("https://github.com:swarm-robotics/sierra-sample-project.git", - "https://github.com:swarm-robotics/sierra-sample-project.git"), - "SIERRA_DOCS": ("https://swarm-robotics-sierra.readthedocs.io/en/master", - "https://swarm-robotics-sierra.readthedocs.io/en/master"), + "SIERRA_GITHUB": ("https://github.com:jharwell/sierra.git", + "https://github.com:jharwell/sierra.git"), + "SIERRA_SAMPLE_PROJECT": ("https://github.com:jharwell/sierra-sample-project.git", + "https://github.com:jharwell/sierra-sample-project.git"), + "SIERRA_DOCS": ("https://sierra.readthedocs.io/en/master", + "https://sierra.readthedocs.io/en/master"), "FORDYCA": ("FORDYCA", "https://swarm-robotics-fordyca.readthedocs.io"), "PRISM": ("PRISM", "https://swarm-robotics-prism.readthedocs.io"), "LIBRA": ("LIBRA", "https://swarm-robotics-libra.readthedocs.io"), diff --git a/docs/src/matrix.rst b/docs/src/matrix.rst index 59c1884d..f4cbf52f 100644 --- a/docs/src/matrix.rst +++ b/docs/src/matrix.rst @@ -96,7 +96,7 @@ listed, see the :ref:`ln-sierra-tutorials` for how to add it via a plugin. SIERRA also supports multiple output formats for experimental outputs. If the format for your experimental outputs is not listed, see the `docs -`_ +`_ for how to add it via a plugin. SIERRA currently only supports XML experimental inputs. diff --git a/docs/src/packages.rst b/docs/src/packages.rst index e8909698..01bd4c50 100644 --- a/docs/src/packages.rst +++ b/docs/src/packages.rst @@ -53,7 +53,7 @@ SIERRA provides a :term:`ROS1` package containing functionality it uses to manage simulations and provide run-time support to :term:`projects` using a :term:`Platform` built on ROS. To use SIERRA with a ROS platform, you need to setup the SIERRA ROSbridge package here (details in README): -``_. +``_. This package provides the following nodes: diff --git a/docs/src/requirements.rst b/docs/src/requirements.rst index 9a519d78..1ea097e7 100644 --- a/docs/src/requirements.rst +++ b/docs/src/requirements.rst @@ -210,7 +210,7 @@ These requirements apply to any :term:`Platform` which uses :term:`ROS1` (e.g., the elapsed time in seconds, and which exits (and takes down the roslaunch when it does) after the specified experiment time has elapsed. This node is inserted into all ``.launch`` files. All ROS projects must depend on this - `ROS bridge `_ + `ROS bridge `_ package so the necessary nodes can be found by ROS at runtime. diff --git a/docs/src/trial.rst b/docs/src/trial.rst index 14126de4..71c1cb46 100755 --- a/docs/src/trial.rst +++ b/docs/src/trial.rst @@ -91,10 +91,10 @@ you clone things somewhere else. Where ```` is replaced by your ROS distro. - #. Install the `SIERRA ROSBridge `_:: + #. Install the `SIERRA ROSBridge `_:: pip3 install catkin_tools - git clone https://github.com/swarm-robotics/sierra_rosbridge.git + git clone https://github.com/jharwell/sierra_rosbridge.git cd sierra_rosbridge catkin init catkin config --extend /opt/ros/ @@ -117,7 +117,7 @@ you clone things somewhere else. Based on the `foraging example `_ from the ARGoS website:: - git clone https://github.com/swarm-robotics/sierra-sample-project.git + git clone https://github.com/jharwell/sierra-sample-project.git cd sierra-sample-project/argos git checkout devel mkdir -p build && cd build @@ -135,7 +135,7 @@ you clone things somewhere else. Based on one of the turtlebot3 `intro tutorials `_:: - git clone https://github.com/swarm-robotics/sierra-sample-project.git + git clone https://github.com/jharwell/sierra-sample-project.git cd sierra-sample-project/ros1gazebo git checkout devel catkin init diff --git a/setup.py b/setup.py index d1103465..65578565 100644 --- a/setup.py +++ b/setup.py @@ -41,7 +41,7 @@ description="Automation framework for the scientific method in AI research", long_description=readme, long_description_content_type="text/x-rst", - url="https://github.com/swarm-robotics/sierra", + url="https://github.com/jharwell/sierra", author="John Harwell", author_email="john.r.harwell@gmail.com", license="GPLv3+", diff --git a/sierra/core/cmdline.py b/sierra/core/cmdline.py index 6e7d0ef9..97f20efa 100755 --- a/sierra/core/cmdline.py +++ b/sierra/core/cmdline.py @@ -34,7 +34,7 @@ "SIERRA comes with no warranty.\n\n" "See the documentation at " - "https://swarm-robotics-sierra.readthedocs.io/en/master/,\n" + "https://sierra.readthedocs.io/en/master/,\n" "or 'man sierra' for details.\n") diff --git a/sierra/version.py b/sierra/version.py index 213eb5fd..7795d36a 100644 --- a/sierra/version.py +++ b/sierra/version.py @@ -20,4 +20,4 @@ # Project packages -__version__ = "1.2.21" +__version__ = "1.2.22"