[doc] Added a custom Lexer for shell code-blocks

doc/source/_ext/console_lexer.py

@@ -0,0 +1,128 @@
+from pygments.lexers import get_lexer_by_name  # refer LEXERS
+from pygments.lexers._mapping import LEXERS
+from pygments.lexers.python import PythonLexer
+from pygments.lexers.shell import BashLexer
+from pygments.token import Name, Keyword
+
+
+import re
+
+from pygments.lexer import Lexer, RegexLexer, do_insertions, bygroups, \
+    include, default, this, using, words, line_re
+from pygments.token import Punctuation, Whitespace, \
+    Text, Comment, Operator, Keyword, Name, String, Number, Generic
+from pygments.util import shebang_matches
+
+
+def setup(app):
+    # choose one, both ok
+    app.add_lexer('shell', BashLexerExt)
+    # app.add_lexer('my_lang', PythonLexer)
+
+class BashLexerExt(RegexLexer):
+    """
+    Lexer for (ba|k|z|)sh shell scripts.
+    """
+
+    name = 'Bash'
+    aliases = ['bash', 'sh', 'ksh', 'zsh', 'shell', 'openrc']
+    filenames = ['*.sh', '*.ksh', '*.bash', '*.ebuild', '*.eclass',
+                 '*.exheres-0', '*.exlib', '*.zsh',
+                 '.bashrc', 'bashrc', '.bash_*', 'bash_*', 'zshrc', '.zshrc',
+                 '.kshrc', 'kshrc',
+                 'PKGBUILD']
+    mimetypes = ['application/x-sh', 'application/x-shellscript', 'text/x-shellscript']
+    url = 'https://en.wikipedia.org/wiki/Unix_shell'
+    version_added = '0.6'
+
+    tokens = {
+        'root': [
+            include('basic'),
+            (r'`', String.Backtick, 'backticks'),
+            include('data'),
+            include('interp'),
+        ],
+        'interp': [
+            (r'\$\(\(', Keyword, 'math'),
+            (r'\$\(', Keyword, 'paren'),
+            (r'\$\{#?', String.Interpol, 'curly'),
+            (r'\$[a-zA-Z_]\w*', Name.Variable),  # user variable
+            (r'\$(?:\d+|[#$?!_*@-])', Name.Variable),      # builtin
+            (r'\$', Text),
+        ],
+        'basic': [
+            (r'\b(if|fi|else|while|in|do|done|for|then|return|function|case|'
+             r'select|break|continue|until|esac|elif)(\s*)\b',
+             bygroups(Keyword, Whitespace)),
+            (r'\b(alias|bg|bind|builtin|caller|cd|command|compgen|'
+             r'complete|declare|dirs|disown|echo|enable|eval|exec|exit|'
+             r'export|false|fc|fg|getopts|hash|help|history|jobs|kill|let|'
+             r'local|logout|popd|printf|pushd|pwd|read|readonly|set|shift|'
+             r'shopt|source|suspend|test|time|times|trap|true|type|typeset|'
+             r'ulimit|umask|unalias|unset|wait|'
+             # Custom added keywords
+             r'sudo|apt|apt-get|apt-cache|mkdir|rosdep|git|roslaunch|pip|vcs|catkin_make|'
+             r'python|make'
+             # End of custom added keywords
+             r')(?=[\s)`])',
+             Name.Builtin),
+            (r'\A#!.+\n', Comment.Hashbang),
+            (r'#.*\n', Comment.Single),
+            (r'\\[\w\W]', String.Escape),
+            (r'(\b\w+)(\s*)(\+?=)', bygroups(Name.Variable, Whitespace, Operator)),
+            (r'[\[\]{}()=]', Operator),
+            (r'<<<', Operator),  # here-string
+            (r'<<-?\s*(\'?)\\?(\w+)[\w\W]+?\2', String),
+            (r'&&|\|\|', Operator),
+        ],
+        'data': [
+            (r'(?s)\$?"(\\.|[^"\\$])*"', String.Double),
+            (r'"', String.Double, 'string'),
+            (r"(?s)\$'(\\\\|\\[0-7]+|\\.|[^'\\])*'", String.Single),
+            (r"(?s)'.*?'", String.Single),
+            (r';', Punctuation),
+            (r'&', Punctuation),
+            (r'\|', Punctuation),
+            (r'\s+', Whitespace),
+            (r'\d+\b', Number),
+            (r'[^=\s\[\]{}()$"\'`\\<&|;]+', Text),
+            (r'<', Text),
+        ],
+        'string': [
+            (r'"', String.Double, '#pop'),
+            (r'(?s)(\\\\|\\[0-7]+|\\.|[^"\\$])+', String.Double),
+            include('interp'),
+        ],
+        'curly': [
+            (r'\}', String.Interpol, '#pop'),
+            (r':-', Keyword),
+            (r'\w+', Name.Variable),
+            (r'[^}:"\'`$\\]+', Punctuation),
+            (r':', Punctuation),
+            include('root'),
+        ],
+        'paren': [
+            (r'\)', Keyword, '#pop'),
+            include('root'),
+        ],
+        'math': [
+            (r'\)\)', Keyword, '#pop'),
+            (r'\*\*|\|\||<<|>>|[-+*/%^|&<>]', Operator),
+            (r'\d+#[\da-zA-Z]+', Number),
+            (r'\d+#(?! )', Number),
+            (r'0[xX][\da-fA-F]+', Number),
+            (r'\d+', Number),
+            (r'[a-zA-Z_]\w*', Name.Variable),  # user variable
+            include('root'),
+        ],
+        'backticks': [
+            (r'`', String.Backtick, '#pop'),
+            include('root'),
+        ],
+    }
+
+    def analyse_text(text):
+        if shebang_matches(text, r'(ba|z|)sh'):
+            return 1
+        if text.startswith('$ '):
+            return 0.2

doc/source/conf.py

@@ -16,6 +16,8 @@
 import sys
 sys.path.insert(0, os.path.abspath(os.path.join("..", "src", "pycram")))
 sys.path.append(os.path.abspath("./_pygments"))
+sys.path.append(os.path.abspath("./_ext"))
+
 
 # -- Project information -----------------------------------------------------
 
@@ -48,6 +50,7 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.autosummary",
     "nbsphinx",
+    "console_lexer",
 ]
 
 # auto api setup

doc/source/installation.rst

@@ -34,7 +34,7 @@ The dependencies you will need are:
 These are available via the Ubuntu apt-repos and can be installed via the terminal:
 
 
-.. code-block:: console
+.. code-block:: shell
 
     sudo apt-get install python3-pip python3-vcstool
 
@@ -44,7 +44,7 @@ PyCRAM on Ubuntu 20.04 (ROS Noetic)
 
 Before installing PyCRAM you need to setup a ROS workspace into which PyCRAM can be cloned.
 
-.. code-block:: console
+.. code-block:: shell
 
     mkdir -p ~/workspace/ros/src
     cd workspace/ros
@@ -54,14 +54,14 @@ Before installing PyCRAM you need to setup a ROS workspace into which PyCRAM can
 If ``catkin_make`` does not work this probably means that you did not source your ROS installation.
 Source it by invoking:
 
-.. code-block:: console
+.. code-block:: shell
 
     source /opt/ros/noetic/setup.bash
 
 
 Now you can install PyCRAM into your ROS workspace.
 
-.. code-block:: console
+.. code-block:: shell
 
     cd ~/workspace/ros/src
     vcs import --input https://raw.githubusercontent.com/cram2/pycram/dev/pycram.rosinstall --recursive
@@ -78,7 +78,7 @@ in your ROS workspace.
 Now the last thing that needs to be done is clone the submodules of the PyCRAM repo, this is done via the following
 commands.
 
-.. code-block:: console
+.. code-block:: shell
 
     cd src/pycram
     git submodule init
@@ -91,20 +91,20 @@ Python Dependencies
 
 To install the Python dependencies Pip is used. To install Pip type the following command into a terminal.
 
-.. code-block:: console
+.. code-block:: shell
 
     sudo apt-get install python3-pip
 
 Now the actual Python packages can be installed, these are summarized in the requirements.txt in the PyCRAM repo.
 For this first navigate to your PyCRAM repo.
 
-.. code-block:: console
+.. code-block:: shell
 
     cd ~/workspace/ros/src/pycram
 
 Then install the Python packages in the requirements.txt file
 
-.. code-block:: console
+.. code-block:: shell
 
     sudo pip3 install -r requirements.txt
     sudo pip3 install -r src/neem_interface_python/requirements.txt
@@ -121,7 +121,7 @@ If you have been following the tutorial steps until now you can skip this part.
 
 You can build your ROS workspace with the following commands:
 
-.. code-block:: console
+.. code-block:: shell
 
     cd ~/workspace/ros
     catkin_make
@@ -135,7 +135,7 @@ and is named "ik_and_description.launch".
 
 The launchfile can be started with the following command:
 
-.. code-block:: console
+.. code-block:: shell
 
     roslaunch pycram ik_and_description.launch
 
@@ -150,25 +150,25 @@ The documentation uses sphinx as engine.
 Building sphinx based documentations requires pandoc
 to be installed. Pandoc can be installed via the package manager of Ubuntu.
 
-.. code-block:: console
+.. code-block:: shell
 
     sudo apt install pandoc
 
 After installing pandoc, install sphinx on your device.
 
-.. code-block:: console
+.. code-block:: shell
 
     sudo apt install python3-sphinx
 
 Install the requirements in your python interpreter.
 
-.. code-block:: console
+.. code-block:: shell
 
     pip install -r requirements.txt
 
 Run pycram and build the docs.
 
-.. code-block:: console
+.. code-block:: shell
 
     roslaunch pycram ik_and_description.launch
     make html
@@ -192,7 +192,7 @@ Next, if you have virtual environments that you want to use, you need to make su
 If you create a new environment, make sure to include  `--system-site-packages` in your creation command.
 You can check by activating your environment and calling the import
 
-.. code-block:: console
+.. code-block:: shell
 
     workon your_env
     python -c "import rospy"
@@ -202,13 +202,13 @@ ros workspace including pycram and source it as described in install-pycram_.
 
 After that you have to start PyCharm from the terminal via
 
-.. code-block:: console
+.. code-block:: shell
 
     pycharm-professional
 
 or
 
-.. code-block:: console
+.. code-block:: shell
 
     ~/pycharm/bin/pycharm.sh
 
@@ -227,7 +227,7 @@ Using IPython as REPL
 If you want to use a REPl with PyCRAM you can use IPython for that. IPython can be installed via
 the Ubunutu package manager.
 
-.. code-block:: console
+.. code-block:: shell
 
     sudo apt install ipython3
 
@@ -241,13 +241,13 @@ The startup files are located in ``~/.ipython/profile_default/startup`` along wi
 of the startup files. In this directory create a file called ``00-autoreload.ipy`` and enter the following code to the file.
 
 
-.. code-block:: console
+.. code-block:: shell
 
     %load_ext autoreload
     %autoreload 2
 
 The first line loads the extension to iPython and the second line configures autoreload to reload all modules before the
-code in the console is executed.
+code in the shell is executed.
 
 
 Run scripts
@@ -257,7 +257,7 @@ IPython allows to run Python files and enabled the access to created variables.
 if you want to create a setup script which initializes things like the BulletWorld, Objects and imports
 relevant modules.
 
-To execute a Python script simply run ``run filename.py`` in the IPython console.
+To execute a Python script simply run ``run filename.py`` in the IPython shell.
 
 Here is an example how a setup script can look like.
 

doc/source/remarks.rst

@@ -12,7 +12,7 @@ to correctly set up the jupyter server, however the notebook will always use you
 
 To fix this issue one has to execute
 
-.. code-block:: console
+.. code-block:: shell
 
     python -m ipykernel install --user --name <kernel_name> --display-name "<Name_to_display>"
 
@@ -40,7 +40,7 @@ Missing pr2_arm_kinematics
 
 Aptitudes autoremove likes to also remove the arm kinematics. Reinstall the missing libraries with
 
-.. code-block:: console
+.. code-block:: shell
 
     sudo apt-get install ros-noetic-moveit
 

doc/source/troubleshooting.rst

@@ -18,7 +18,7 @@ file was not launched.
 To solve this problem you just have to launch the ``ik_and_description`` file of PyCRAM. This can be done via the
 following command.
 
-.. code-block:: bash
+.. code-block:: shell
 
     roslaunch pycram ik_and_description