Merge pull request #174 from SimonRohou/codac2_dev

Doc

doc/manual/_static/css/custom.css

@@ -10,4 +10,10 @@
 a.sidebar-brand {
   padding: 2rem 0rem;
   padding-right: 1rem;
+}
+
+.sidebar-logo
+{
+  max-width: 120%;
+  float: right;
 }

doc/manual/development/info_dev.rst

@@ -0,0 +1,24 @@
+Information for developers
+==========================
+
+Building the Manual with Sphinx
+-------------------------------
+
+To build this manual using Sphinx, follow these steps:
+
+1. **Requirements**: Install `Sphinx <https://www.sphinx-doc.org/>`_ together with the extensions used by Codac, if they are not already installed.
+
+   .. code-block:: bash
+
+      pip install sphinx furo sphinx-math-dollar
+
+2. **Building the manual**: After configuring the CMake project, the manual can be build with:
+
+   .. code-block:: bash
+
+      make manual
+
+   The generated website will be locally available in ``./build/doc/manual``.
+
+To contribute and extend this manual, please consult the Sphinx documentation:  
+https://www.sphinx-doc.org

doc/manual/index.rst

@@ -58,11 +58,12 @@ Welcome to the Codac website.
 ..    howto/dynamical/index.rst
 
 
-.. .. toctree::
-..    :hidden:
-..    :caption: Development
-..    :maxdepth: 3
+.. toctree::
+   :hidden:
+   :caption: Development
+   :maxdepth: 3
+
+   development/info_dev.rst
 .. 
 ..    Changelog <http://codac.io>
 ..    C++ API <http://codac.io>
-..    Information for developers <http://codac.io>

doc/manual/installation/cpp.rst

@@ -1,3 +1,5 @@
+.. _sec-start-cpp-project:
+
 C++ installation
 ================
 
@@ -20,4 +22,6 @@ C++ installation
 
 
 Using Codac in CMake projects
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+...

doc/manual/installation/index.rst

@@ -1,6 +1,8 @@
 Installation Guide
 ==================
 
+Codac is available in both C++20 and Python3, as well as MATLAB `through its Python interface <https://fr.mathworks.com/help/matlab/matlab_external/install-supported-python-implementation.html>`_. Note that if you want to contribute to Codac, you have to make the full C++ installation from sources.
+
 .. toctree::
    :maxdepth: 1
 

doc/manual/installation/python.rst

@@ -1,9 +1,55 @@
+.. _sec-start-py-project:
+
 Python installation
 ===================
 
+In case you want to use Codac only with Python, then the installation procedure is simply:
+
 1. **Dependencies**: Ensure you have a supported version of Python (>=3.6).
 2. **Install via pip**: Use the following command to install Codac:
 
    .. code-block:: bash
    
-      pip install codac
+      pip install codac
+
+
+You can also update and test your Codac Python package.
+
+* **Update via pip**: Use the following command to update your already installed Codac package:
+   .. code-block:: bash
+
+      pip install codac --upgrade
+
+
+* **Testing the installation**: In order to verify that your installation is working properly in Python, you can run:
+   .. code-block:: bash
+
+     python -m unittest discover codac.tests
+
+
+Troubleshooting
+---------------
+
+Depending on your configuration, you may encounter difficulties when installing the Codac Python package. Here are a few tips to help you.
+
+.. admonition:: Debian Bookworm and possibly other configurations
+
+  | ``pip install ...`` or ``pip3 install ...`` commands may only work inside `virtual environments <https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/>`_ or with ``--break-system-packages`` parameter, *e.g.*:
+
+  .. code-block:: bash
+
+    pip3 install --break-system-packages codac
+
+.. admonition:: macOS Big Sur and later (x86_64)
+
+  | Python wheels provided for Catalina or earlier `may need to be installed with something similar to <https://stackoverflow.com/questions/64847996/force-usage-of-10-x-wheel-in-macos-big-sur>`_: 
+
+  .. code-block:: bash
+
+    sudo pip3 install --upgrade vibes # Add here any other non-binary wheels dependencies...
+    sudo pip3 install --upgrade --nodeps --platform macosx_10_9_x86_64 --only-binary=:all: --target=/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.8/lib/python3.8/site-packages codac
+
+  Depending on the way Python was installed, the path to specify after ``--target`` may differ, *e.g.* if Python was installed from https://www.python.org/ftp/python/3.10.4/python-3.10.4-macos11.pkg, it may be ``/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages``. Otherwise, run ``python3 -m site`` to check the ``site-packages`` full path in ``sys.path`` list. Also, the value ``10_9`` may need to be changed to ``10_14`` (or possibly another value) for some Python versions.
+
+
+Finally, note that unsupported configurations can still probably follow the instructions from :ref:`Installing local Python binding <sec-manual-dev>`, for building the Codac Python binding locally on your machine.