From c42ff66c6fa49b4053d8f1d761e227cdc0988825 Mon Sep 17 00:00:00 2001 From: lebarsfa Date: Wed, 6 Mar 2024 23:38:11 +0100 Subject: [PATCH] Documentation updates --- doc/doc/install/01-installation-full-linux.rst | 2 +- doc/doc/install/01-installation-full-macos.rst | 17 +++++++++++++---- .../install/01-installation-full-windows.rst | 17 +++++++---------- doc/doc/install/02-start-py-project.rst | 3 +-- doc/doc/install/03-start-cpp-project.rst | 3 +-- doc/doc/install/04-start-matlab-project.rst | 7 +++++++ 6 files changed, 30 insertions(+), 19 deletions(-) diff --git a/doc/doc/install/01-installation-full-linux.rst b/doc/doc/install/01-installation-full-linux.rst index 88375c110..d69113f5a 100644 --- a/doc/doc/install/01-installation-full-linux.rst +++ b/doc/doc/install/01-installation-full-linux.rst @@ -27,7 +27,7 @@ Then, check your installation `with the instructions of this page <03-start-cpp- .. note:: - For a Raspberry Pi running Raspbian Buster, download and extract ``codac_standalone_armv6hf_buster.zip`` from ``_, then in the ``example`` folder run: + For a Raspberry Pi running Raspbian Buster 32 bit, download and extract ``codac_standalone_armv6hf_buster.zip`` from ``_, then in the ``example`` folder run: .. code-block:: bash diff --git a/doc/doc/install/01-installation-full-macos.rst b/doc/doc/install/01-installation-full-macos.rst index eb479e55a..c0ca9f64c 100644 --- a/doc/doc/install/01-installation-full-macos.rst +++ b/doc/doc/install/01-installation-full-macos.rst @@ -10,7 +10,7 @@ Installing Codac on macOS for C++ use Quick start ----------- -Install Homebrew package manager and build tools: +Install `Homebrew package manager `_ and build tools: .. code-block:: bash @@ -18,7 +18,7 @@ Install Homebrew package manager and build tools: brew install wget autoconf automake libtool brew install --cask cmake -Download and extract *e.g.* ``codac_standalone_x86_64_bigsur.zip`` (for macOS 11 Big Sur (x86_64)) from ``_, then in ``example`` folder run: +Download and extract *e.g.* ``codac_standalone_arm64_monterey.zip`` (for macOS 12 Monterey on a Mac with Apple silicon (arm64 processor), use ``codac_standalone_x86_64_monterey.zip`` for a Mac with an Intel processor (x86_64 processor), see https://support.apple.com/en-us/116943) from ``_, then in ``example`` folder run: .. code-block:: bash @@ -26,16 +26,25 @@ Download and extract *e.g.* ``codac_standalone_x86_64_bigsur.zip`` (for macOS 11 and check that "My first tube:Tube [0, 10]" appears. -Optionally, download and run ``_ (see also https://support.apple.com/HT211861) before running the project, and check that a tube appears in VIBes window. +Optionally, download and run ``_ (see also https://support.apple.com/HT211861) before running the project, and check that a tube appears in :ref:`VIBes viewer `. Building from sources --------------------- -You will probably need to install those prerequisites (assuming you installed `Homebrew package manager `_): +You will probably need to install those prerequisites: .. code-block:: bash brew install eigen +Optionally, for Python and documentation: + +.. code-block:: bash + + wget https://github.com/Homebrew/homebrew-core/raw/d2267b9f2ad247bc9c8273eb755b39566a474a70/Formula/doxygen.rb ; brew reinstall ./doxygen.rb ; brew pin doxygen + brew install graphviz + python -m pip install --upgrade pip + pip install --upgrade wheel setuptools sphinx breathe sphinx-issues sphinx-tabs sphinx_rtd_theme sphinx-reredirects + The logic to follow will then be similar to `Linux <01-installation-full-linux.html>`_. See also `Information for developers `_. diff --git a/doc/doc/install/01-installation-full-windows.rst b/doc/doc/install/01-installation-full-windows.rst index 2771e8610..d52a27757 100644 --- a/doc/doc/install/01-installation-full-windows.rst +++ b/doc/doc/install/01-installation-full-windows.rst @@ -17,9 +17,9 @@ Check https://community.chocolatey.org/packages/codac. .. rubric:: Using Visual Studio -Download and extract *e.g.* ``codac_standalone_x64_vc16.zip`` (for Visual Studio 2019) from ``_, open ``example\CMakelists.txt``, choose ``x64-Release`` configuration in Visual Studio (instead of ``x64-Debug``), double-click on ``main.cpp`` in the Solution Explorer and then click on the green Start button, finally check that "My first tube:Tube [0, 10]" appears. +Download and extract *e.g.* ``codac_standalone_x64_vc17.zip`` (for Visual Studio 2022) from ``_, open ``example\CMakelists.txt``, choose ``x64-Release`` configuration in Visual Studio (instead of ``x64-Debug``), double-click on ``main.cpp`` in the Solution Explorer and then click on the green Start button, finally check that "My first tube:Tube [0, 10]" appears. -Optionally, download and run ``_ before running the project, and check that a tube appears in VIBes window. +Optionally, download and run ``_ before running the project, and check that a tube appears in :ref:`VIBes viewer `. Building from sources @@ -32,19 +32,16 @@ You will probably need to install these prerequisites (assuming you installed `C choco install cmake git make patch winflexbison choco install eigen -Then, install the desired compiler (*e.g.* ``choco install mingw --version=8.1.0``). +Then, install the desired compiler (*e.g.* ``choco install mingw --version=11.2.0.07112021``). -Optionally, for Python (*e.g.* ``choco install python --version=3.8.2``) and documentation: +Optionally, for Python (*e.g.* ``choco install python --version=3.10.4``) and documentation: .. code-block:: bat - choco install doxygen.install graphviz + choco install doxygen.install --version=1.9.6 + choco install graphviz python -m pip install --upgrade pip - pip install --upgrade wheel setuptools - git clone --depth 1 -b v3.1.1 https://github.com/sphinx-doc/sphinx - cd sphinx - pip install . - pip install --upgrade breathe sphinx-issues sphinx-tabs sphinx_rtd_theme sphinx-reredirects + pip install --upgrade wheel setuptools sphinx breathe sphinx-issues sphinx-tabs sphinx_rtd_theme sphinx-reredirects The logic to follow will then be similar to `Linux <01-installation-full-linux.html>`_ (note that for Visual Studio, commands such as ``make install`` need to be replaced with something similar to: diff --git a/doc/doc/install/02-start-py-project.rst b/doc/doc/install/02-start-py-project.rst index 5a40f330b..7e9ee6c15 100644 --- a/doc/doc/install/02-start-py-project.rst +++ b/doc/doc/install/02-start-py-project.rst @@ -8,8 +8,7 @@ Start a Python project | You are using C++? | :ref:`sec-start-cpp-project` -| Codac is ready to be used on your computer. -| You can now import the ``codac`` package and start using it: +| Assuming :ref:`Codac Python package is installed `, you can import the ``codac`` package and start using it: .. code-block:: py diff --git a/doc/doc/install/03-start-cpp-project.rst b/doc/doc/install/03-start-cpp-project.rst index 49f1b5335..335b9c3da 100644 --- a/doc/doc/install/03-start-cpp-project.rst +++ b/doc/doc/install/03-start-cpp-project.rst @@ -8,8 +8,7 @@ Start a C++ project | You are using Python? | :ref:`sec-start-py-project` -| Codac is ready to be used on your computer. -| You can now copy-paste the following example code in a file named :file:`main.cpp`: +| Assuming :ref:`Codac library is installed `, you can copy-paste the following example code in a file named :file:`main.cpp`: .. code-block:: c++ diff --git a/doc/doc/install/04-start-matlab-project.rst b/doc/doc/install/04-start-matlab-project.rst index b69699ea5..18dfc823c 100644 --- a/doc/doc/install/04-start-matlab-project.rst +++ b/doc/doc/install/04-start-matlab-project.rst @@ -47,3 +47,10 @@ In order to visualize the tube, you need to launch before the :ref:`VIBes viewer If everything is well installed on your computer, you should see the following window appear: .. Figure:: img/helloworld.png + +.. warning:: + + Octave support is more limited than MATLAB at the moment (and only briefly tested on Ubuntu 22.04 for now). `Pythonic `_ needs to be installed to be able to call Python code from Octave. It has currently some limitations (see https://wiki.octave.org/Pythonic) such as: + + * Missing `import` command. https://gist.github.com/lebarsfa/ebc19b143df77753842f920b4b680b84#file-import-m can be loaded in Octave as a workaround. + * Operators such as `+`, `-`, `*`, `/`, `==`, `!=`, etc. do not seem overloaded (see https://gitlab.com/gnu-octave/octave-pythonic/-/issues/129, note that these operators are supported by MATLAB, but some others might not be supported by MATLAB either, see the bottom of https://fr.mathworks.com/help/matlab/matlab_external/differences-between-matlab-python.html). The internal methods `__add__()`, `__sub__()`, `__neg__()`, `__mul__()`, `__truediv__()`, `__eq__()`, `__ne__()`, etc. can be used instead.