From 982155cc02b045c621aeb72eb6abbca96af720dd Mon Sep 17 00:00:00 2001 From: Simon Rohou Date: Wed, 8 Jan 2025 17:27:50 +0100 Subject: [PATCH] [doc] install + info dev --- doc/manual/_static/css/custom.css | 6 ++++ doc/manual/development/info_dev.rst | 24 +++++++++++++++ doc/manual/index.rst | 11 ++++--- doc/manual/installation/cpp.rst | 6 +++- doc/manual/installation/index.rst | 2 ++ doc/manual/installation/python.rst | 48 ++++++++++++++++++++++++++++- 6 files changed, 90 insertions(+), 7 deletions(-) create mode 100644 doc/manual/development/info_dev.rst diff --git a/doc/manual/_static/css/custom.css b/doc/manual/_static/css/custom.css index fbc9b289..50ffda48 100644 --- a/doc/manual/_static/css/custom.css +++ b/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; } \ No newline at end of file diff --git a/doc/manual/development/info_dev.rst b/doc/manual/development/info_dev.rst new file mode 100644 index 00000000..426f8c09 --- /dev/null +++ b/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 `_ 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 \ No newline at end of file diff --git a/doc/manual/index.rst b/doc/manual/index.rst index 97584dbf..beee9bae 100644 --- a/doc/manual/index.rst +++ b/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 .. C++ API -.. Information for developers \ No newline at end of file diff --git a/doc/manual/installation/cpp.rst b/doc/manual/installation/cpp.rst index 2c8a414c..c9867afd 100644 --- a/doc/manual/installation/cpp.rst +++ b/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 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ \ No newline at end of file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +... \ No newline at end of file diff --git a/doc/manual/installation/index.rst b/doc/manual/installation/index.rst index 932dd8f7..f366c446 100644 --- a/doc/manual/installation/index.rst +++ b/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 `_. Note that if you want to contribute to Codac, you have to make the full C++ installation from sources. + .. toctree:: :maxdepth: 1 diff --git a/doc/manual/installation/python.rst b/doc/manual/installation/python.rst index f044fdcb..044842b4 100644 --- a/doc/manual/installation/python.rst +++ b/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 \ No newline at end of file + 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 `_ 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 `_: + + .. 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 `, for building the Codac Python binding locally on your machine. \ No newline at end of file