From 1a259e14b888c0789e696200269c9f37b5aca0b0 Mon Sep 17 00:00:00 2001 From: Jonas Dech Date: Thu, 4 Jan 2024 21:26:40 +0100 Subject: [PATCH 1/3] [doc] Better style --- doc/source/_pygments/style.py | 7 +++++++ doc/source/conf.py | 4 ++-- 2 files changed, 9 insertions(+), 2 deletions(-) create mode 100644 doc/source/_pygments/style.py diff --git a/doc/source/_pygments/style.py b/doc/source/_pygments/style.py new file mode 100644 index 000000000..27627d59c --- /dev/null +++ b/doc/source/_pygments/style.py @@ -0,0 +1,7 @@ +from pygments.styles.gruvbox import GruvboxLightStyle + + +class BetterGruvboxLightStyle(GruvboxLightStyle): + + highlight_color = '#ddd6a6' + #highlight_color = '#ffffff' \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index cb9889b21..22d8f5f3a 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -15,7 +15,7 @@ import os import sys sys.path.insert(0, os.path.abspath(os.path.join("..", "src", "pycram"))) - +sys.path.append(os.path.abspath("./_pygments")) # -- Project information ----------------------------------------------------- @@ -86,7 +86,7 @@ # pygments_style = "sphinx" # pygments_style = "monokai" -pygments_style = "colorful" +pygments_style = "style.BetterGruvboxLightStyle" # -- Options for HTML output ------------------------------------------------- From 7c5b6874ed72e6fb39d7a1d711b530868ba7a3b7 Mon Sep 17 00:00:00 2001 From: Jonas Dech Date: Thu, 4 Jan 2024 23:57:09 +0100 Subject: [PATCH 2/3] [doc] Added a custom Lexer for shell code-blocks --- doc/source/_ext/console_lexer.py | 128 +++++++++++++++++++++++++++++++ doc/source/conf.py | 3 + doc/source/installation.rst | 42 +++++----- doc/source/remarks.rst | 4 +- doc/source/troubleshooting.rst | 2 +- 5 files changed, 155 insertions(+), 24 deletions(-) create mode 100644 doc/source/_ext/console_lexer.py diff --git a/doc/source/_ext/console_lexer.py b/doc/source/_ext/console_lexer.py new file mode 100644 index 000000000..91052e2e1 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index 22d8f5f3a..ca9bf7204 100644 --- a/doc/source/conf.py +++ b/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 diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 847a536ff..32625f5b1 100644 --- a/doc/source/installation.rst +++ b/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. diff --git a/doc/source/remarks.rst b/doc/source/remarks.rst index e58a358a9..9b7003f6d 100644 --- a/doc/source/remarks.rst +++ b/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 --display-name "" @@ -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 diff --git a/doc/source/troubleshooting.rst b/doc/source/troubleshooting.rst index 62ed9eaf3..5a1136717 100644 --- a/doc/source/troubleshooting.rst +++ b/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 From 0f0b3aaecf4c52d1ac65fc7230965706e3c27bb7 Mon Sep 17 00:00:00 2001 From: Jonas Dech Date: Fri, 5 Jan 2024 00:25:12 +0100 Subject: [PATCH 3/3] [doc] Cleanup of lexer and conf --- doc/source/_ext/console_lexer.py | 17 ++++------------- doc/source/conf.py | 3 --- 2 files changed, 4 insertions(+), 16 deletions(-) diff --git a/doc/source/_ext/console_lexer.py b/doc/source/_ext/console_lexer.py index 91052e2e1..e8e80ba27 100644 --- a/doc/source/_ext/console_lexer.py +++ b/doc/source/_ext/console_lexer.py @@ -1,12 +1,3 @@ -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, \ @@ -15,11 +6,11 @@ def setup(app): - # choose one, both ok - app.add_lexer('shell', BashLexerExt) - # app.add_lexer('my_lang', PythonLexer) + app.add_lexer('shell', BashLexerExtended) + app.add_lexer('console', BashLexerExtended) + -class BashLexerExt(RegexLexer): +class BashLexerExtended(RegexLexer): """ Lexer for (ba|k|z|)sh shell scripts. """ diff --git a/doc/source/conf.py b/doc/source/conf.py index ca9bf7204..2c9f82319 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -86,9 +86,6 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # The name of the Pygments (syntax highlighting) style to use. -# pygments_style = "sphinx" -# pygments_style = "monokai" - pygments_style = "style.BetterGruvboxLightStyle"