doc: Fixes README.rst errors and erroneous content-type in setup.py.

Change-Id: Iaf4999e85f11e128b8e65ae54c44302861dc1bf5
Reviewed-on: http://gerrit2.aldebaran.lan/1371
Reviewed-by: jmonnon <jmonnon@aldebaran.com>
Reviewed-by: philippe.martin <philippe.martin@softbankrobotics.com>
Tested-by: vincent.palancher <vincent.palancher@softbankrobotics.com>

Author: Vincent Palancher

README.rst

@@ -2,27 +2,30 @@
 LibQiPython - LibQi Python bindings
 ===================================
 
-This repository contains the official Python bindings of the `LibQi`_, the `qi`
+This repository contains the official Python bindings of the `LibQi`__, the ``qi``
 Python module.
 
+__ LibQi_repo_
+
 Building
 ========
 
-This project supports the building of a "standalone" package (for instance as a
+This project supports the building of a *standalone* package (for instance as a
 wheel that can be uploaded on PyPi_) or of a "system" archive.
 
 .. _standalone:
+
 Standalone (wheel)
 ------------------
 
-This build mode is also referred to as the "standalone" mode. It is enabled by
-passing `-DQIPYTHON_STANDALONE=ON` to the CMake call. The Python setup script
+This build mode is also referred to as the *standalone* mode. It is enabled by
+passing ``-DQIPYTHON_STANDALONE=ON`` to the CMake call. The Python setup script
 also sets this mode automatically when used.
 
 In this mode, the project will build libqi and install all its dependencies as
 part of the project.
 
-The package can be built from the `setup.py` script:
+The package can be built from the ``setup.py`` script:
 
 .. code:: bash
 
@@ -42,7 +45,7 @@ handles any option the latter can handle. Additionally, it can take CMake
 arguments, which means that you can almost entirely customize how the native
 part is built.
 
-In particular, you can use the `CMAKE_TOOLCHAIN_FILE` variable to specify a
+In particular, you can use the ``CMAKE_TOOLCHAIN_FILE`` variable to specify a
 toolchain to build the native part of the wheel (e.g. if you are using qi
 toolchains):
 
@@ -65,13 +68,13 @@ first build libqi then libqi-python.
   qibuild configure
   qibuild make
 
-You can also set the `QI_DIR` variable at the CMake call to let it know it of
+You can also set the ``QI_DIR`` variable at the CMake call to let it know it of
 the location of the libqi package.
 
 .. code:: bash
 
   mkdir build && cd build
-  cmake .. -DQI_DIR=<path to the libqi installation>
+  cmake .. -DQI_DIR=/path/to/libqi/install/dir
   cmake --build .
 
 
@@ -84,76 +87,78 @@ least CMake v3.17.
 
 Our CMake scripts may take a few parameters:
 
-- `QIPYTHON_STANDALONE`, when set, builds the library in "standalone" mode.
+- ``QIPYTHON_STANDALONE``, when set, builds the library in *standalone* mode.
   Refer to the standalone_ section for details.
-- `QIPYTHON_FORCE_STRIP`, when set, forces the build system to strip the
+- ``QIPYTHON_FORCE_STRIP``, when set, forces the build system to strip the
   libqi-python native module library at install, resulting in a smaller binary.
-- `QI_WITH_TESTS`, when set, enables building of tests. This option is ignored
+- ``QI_WITH_TESTS``, when set, enables building of tests. This option is ignored
   when cross-compiling.
 
 Dependencies
 ~~~~~~~~~~~~
 
 The project has a few dependencies and the build system might report errors if
-it fails to find them. It uses either `FindXXX` CMake modules through the
-`find_package` command or the `FetchContent` module for subprojects. Either way,
-any parameter that these modules and the `find_package` command accept can be
+it fails to find them. It uses either ``FindXXX`` CMake modules through the
+``find_package`` command or the ``FetchContent`` module for subprojects. Either way,
+any parameter that these modules and the ``find_package`` command accept can be
 used to customize how the build system finds the libraries or fetches the
 subprojects.
 
 Most of the variables described here are defined in the
-`cmake/set_dependencies.cmake` file. You may refer to this file for more details
+``cmake/set_dependencies.cmake`` file. You may refer to this file for more details
 on these variables and their values.
 
 LibQi
 >>>>>
 
 The project's dependencies on LibQi depends on the building mode:
 
-- In system mode, it will expect to find it as a binary package. The location
-  of the binary package installation can be specified through the `QI_DIR`
+- In **system mode**, it will expect to find it as a binary package. The location
+  of the binary package installation can be specified through the ``QI_DIR``
   variable.
-- In standalone mode, it will download and compile it as a subproject through
-  the `FetchContent` CMake module. How it is downloaded can be customized
+- In **standalone mode**, it will download and compile it as a subproject through
+  the ``FetchContent`` CMake module. How it is downloaded can be customized
   through the following variables:
 
-  - `LIBQI_VERSION`
-  - `LIBQI_GIT_REPOSITORY`
-  - `LIBQI_GIT_TAG`
+  - ``LIBQI_VERSION``
+  - ``LIBQI_GIT_REPOSITORY``
+  - ``LIBQI_GIT_TAG``
 
 It is possible to skip the download step and use an existing source directory by
-setting its path as the `FETCHCONTENT_SOURCE_DIR_LIBQI` CMake variable. The
+setting its path as the ``FETCHCONTENT_SOURCE_DIR_LIBQI`` CMake variable. The
 build system will still check that the version of the sources matches the
-`LIBQI_VERSION` value if it is set.
+``LIBQI_VERSION`` value if it is set.
 
 Python
 >>>>>>
 
 The build system uses the FindPython_ CMake module. It will try to honor the
 following variables if they are set:
 
-  - `PYTHON_VERSION_STRING`
-  - `PYTHON_LIBRARY`
-  - `PYTHON_INCLUDE_DIR`
+  - ``PYTHON_VERSION_STRING``
+  - ``PYTHON_LIBRARY``
+  - ``PYTHON_INCLUDE_DIR``
 
 pybind11
 >>>>>>>>
 
-The build system will by default download and compile pybind11_ as a
-subproject through the `FetchContent` CMake module. How it is downloaded can be
+The build system will by default download and compile pybind11__ as a
+subproject through the ``FetchContent`` CMake module. How it is downloaded can be
 customized through the following variables:
 
-  - `PYBIND11_VERSION`
-  - `PYBIND11_GIT_REPOSITORY`
-  - `PYBIND11_GIT_TAG`
+__ pybind11_repo_
+
+  - ``PYBIND11_VERSION``
+  - ``PYBIND11_GIT_REPOSITORY``
+  - ``PYBIND11_GIT_TAG``
 
 
 Boost
 >>>>>
 
 The build system will look for the Boost libraries on the system or in the
 toolchain if one is set. The expected version of the libraries is specified as
-the `BOOST_VERSION` variable.
+the ``BOOST_VERSION`` variable.
 
 The build system uses the FindBoost_ CMake module.
 
@@ -170,13 +175,15 @@ The build system uses the FindICU_ CMake module.
 GoogleTest
 >>>>>>>>>>
 
-The build system will by default download and compile GoogleTest_ as a
-subproject through the `FetchContent` CMake module. How it is downloaded can be
+The build system will by default download and compile GoogleTest__ as a
+subproject through the ``FetchContent`` CMake module. How it is downloaded can be
 customized through the following variables:
 
-  - `GOOGLETEST_VERSION`
-  - `GOOGLETEST_GIT_REPOSITORY`
-  - `GOOGLETEST_GIT_TAG`
+__ GoogleTest_repo_
+
+  - ``GOOGLETEST_VERSION``
+  - ``GOOGLETEST_GIT_REPOSITORY``
+  - ``GOOGLETEST_GIT_TAG``
 
 Install
 ~~~~~~~
@@ -195,7 +202,7 @@ Crosscompiling
 --------------
 
 The project supports cross-compiling as explained in the `CMake manual about
-toolchains`__. You may simply set the `CMAKE_TOOLCHAIN_FILE` variable to the
+toolchains`__. You may simply set the ``CMAKE_TOOLCHAIN_FILE`` variable to the
 path of the CMake file in your toolchain.
 
 __ CMake_toolchains_
@@ -210,16 +217,16 @@ When enabled, tests can be executed with `CTest`_.
   cd build
   ctest . --output-on-failure
 
-.. _LibQi: https://github.com/aldebaran/libqi
+.. _LibQi_repo: https://github.com/aldebaran/libqi
 .. _PyPi: https://pypi.org/
 .. _scikit-build: https://scikit-build.readthedocs.io/en/latest/
 .. _setuptools: https://setuptools.readthedocs.io/en/latest/setuptools.html
 .. _qibuild: https://github.com/aldebaran/qibuild
-.. _pybind11: https://pybind11.readthedocs.io/en/latest/
+.. _pybind11_repo: https://pybind11.readthedocs.io/en/latest/
 .. _FindPython: https://cmake.org/cmake/help/latest/module/FindPython.html
 .. _FindBoost: https://cmake.org/cmake/help/latest/module/FindBoost.html
 .. _FindOpenSSL: https://cmake.org/cmake/help/latest/module/FindOpenSSL.html
 .. _FindICU: https://cmake.org/cmake/help/latest/module/FindICU.html
-.. _GoogleTest: https://github.com/google/googletest
+.. _GoogleTest_repo: https://github.com/google/googletest
 .. _CMake_toolchains: https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html
-.. _CTest: https://cmake.org/cmake/help/latest/manual/ctest.1.html
+.. _CTest: https://cmake.org/cmake/help/latest/manual/ctest.1.html

setup.py

@@ -25,7 +25,7 @@
     version=version['__version__'],
     description='LibQi Python bindings',
     long_description=long_description,
-    long_description_content_type='text/markdown',
+    long_description_content_type='text/x-rst',
     keywords=['libqi', 'qi', 'naoqi',
               'softbank', 'robotics', 'aldebaran',
               'robot', 'nao', 'pepper', 'romeo'],