Checks of spelling and fixes in docs

Author: Andrii Verbytskyi

documentation/basics.rst

@@ -48,7 +48,7 @@ do so.
 Running the Binder
 ------------------
 
-After the input file is ready the next step is to run Binder. Assuming that our include file conatining all headers from the
+After the input file is ready the next step is to run Binder. Assuming that our include file containing all headers from the
 project is named as ``all_includes.hpp`` it could be done as:
 
 .. code-block:: bash
@@ -61,7 +61,7 @@ project is named as ``all_includes.hpp`` it could be done as:
 
 
 Note that we have to specify project-wide include path so Binder could find includes specifies in ``all_includes.hpp`` as well
-as path to any aditional C++ include headers that is used in project.
+as path to any additional C++ include headers that is used in project.
 
 Most big project will probably require fine tunning of bindings generation process. This can be done by creating Binder config
 file and specifying it when calling Binder as ``--config my_project.config``. For detailed reference of config file options

documentation/config.rst

@@ -161,27 +161,27 @@ Config file directives:
 
 
 * ``default_static_pointer_return_value_policy``, specify return value policy for static functions returning pointer to objects. Default is
-  'pybind11::return_value_policy::automatic'.
+  `pybind11::return_value_policy::automatic`.
 
 
 * ``default_static_lvalue_reference_return_value_policy``, specify return value policy for static functions returning l-value reference. Default
-  is 'pybind11::return_value_policy::automatic'.
+  is `pybind11::return_value_policy::automatic`.
 
 
 * ``default_static_rvalue_reference_return_value_policy``, specify return value policy for static functions returning r-value reference. Default
-  is 'pybind11::return_value_policy::automatic'.
+  is `pybind11::return_value_policy::automatic`.
 
 
 * ``default_member_pointer_return_value_policy``, specify return value policy for member functions returning pointer to objects. Default is
-  'pybind11::return_value_policy::automatic'.
+  `pybind11::return_value_policy::automatic`.
 
 
 * ``default_member_lvalue_reference_return_value_policy``, specify return value policy for member functions returning l-value reference. Default
-  is 'pybind11::return_value_policy::automatic'.
+  is `pybind11::return_value_policy::automatic`.
 
 
 * ``default_member_rvalue_reference_return_value_policy``, specify return value policy for member functions returning r-value reference. Default
-  is 'pybind11::return_value_policy::automatic'.
+  is `pybind11::return_value_policy::automatic`.
 
 * ``default_call_guard``, optionally specify a call guard applied to all function definitions. See `pybind11 documentation <http://pybind11.readthedocs.io/en/stable/advanced/functions.html#call-guard>`_. Default None.
 

documentation/debugging.rst

@@ -1,5 +1,5 @@
 Debugging and troubleshooting 
-##########
+#############################
 
 This section is dedicated to the description of problems that 
 might appear while creating the python bindings with binder and the ways to avoid them.
@@ -13,15 +13,15 @@ Inconsistencies
 
 Binder moves down the ``all_includes_file`` file sequentially, sometimes ending up with errors.  
 This is almost always caused by the ``all_includes_file`` being
-different between runs.  The order shouldn't be important, but nail it down to at least be
+different between runs.  The order should not be important, but nail it down to at least be
 consistent, and then move on to the next step.
 
 --------------
 Build failures
 --------------
 
 Even when the bindings were generated successfully,  there might be compilation errors when building the modules from the generated sources.
-Quite often  the errors are caused by the implementation of the С++standard library, when the headers of the standard library 
+Quite often  the errors are caused by the implementation of the C++ standard library, when the headers of the standard library 
 include each other, or include implementation-specific headers. 
 Many cases like that are already handled in the functions from the ``source/types.cpp`` file, 
 using the knowledge of the existing STL implementations.
@@ -38,7 +38,7 @@ For instance, the compilation could fail with the following error messages:
 
     FAILED: CMakeFiles/statvec.dir/std/complex.o 
     In file included from std/complex.cpp:1:0:
-    /usr/include/c++/7/bits/stl_construct.h: In function ‘void std::_Destroy(_ForwardIterator, _ForwardIterator)’:
+    /usr/include/c++/7/bits/stl_construct.h: In function 'void std::_Destroy(_ForwardIterator, _ForwardIterator)':
     **long and cryptic error message**
 
 The ways to handle this error:
@@ -47,62 +47,63 @@ The ways to handle this error:
     more information on the binded classes.
 
 2.  Since the includes from the ``bits`` directory should not appear in the generated code,  one can grep for ``bits`` in the generated codes, 
-   i.e. ``grep -r "bits" cmake_bindings/*`` could yield:
-
-.. code-block:: console
-
-    cmake_bindings/std/complex.cpp:#include <bits/stl_construct.h> // std::_Construct
-    cmake_bindings/std/complex.cpp:#include <bits/stl_construct.h> // std::_Destroy
-    cmake_bindings/std/complex.cpp:#include <bits/stl_construct.h> // std::_Destroy_aux
-    cmake_bindings/std/complex.cpp:#include <bits/stl_construct.h> // std::_Destroy_aux<true>::__destroy
-    cmake_bindings/std/complex.cpp:#include <bits/stl_construct.h> // std::_Destroy_n_aux
-    cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_copy
-    cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_copy<false>::__uninit_copy
-    cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_copy<true>::__uninit_copy
-    cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_copy_a
-    cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_default_1
-    cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_default_n
-    cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_default_n_1
-    cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_default_n_1<false>::__uninit_default_n
-    cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_default_n_1<true>::__uninit_default_n
-    cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_default_n_a
-    cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_default_novalue_1
-    cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_default_novalue_n_1
-    cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_fill
-    cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_fill_n
-    cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_move_if_noexcept_a
-    cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::uninitialized_copy
+    i.e. ``grep -r "bits" cmake_bindings/*`` could yield:
+
+
+    .. code-block:: console
+
+      cmake_bindings/std/complex.cpp:#include <bits/stl_construct.h> // std::_Construct
+      cmake_bindings/std/complex.cpp:#include <bits/stl_construct.h> // std::_Destroy
+      cmake_bindings/std/complex.cpp:#include <bits/stl_construct.h> // std::_Destroy_aux
+      cmake_bindings/std/complex.cpp:#include <bits/stl_construct.h> // std::_Destroy_aux<true>::__destroy
+      cmake_bindings/std/complex.cpp:#include <bits/stl_construct.h> // std::_Destroy_n_aux
+      cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_copy
+      cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_copy<false>::__uninit_copy
+      cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_copy<true>::__uninit_copy
+      cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_copy_a
+      cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_default_1
+      cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_default_n
+      cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_default_n_1
+      cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_default_n_1<false>::__uninit_default_n
+      cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_default_n_1<true>::__uninit_default_n
+      cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_default_n_a
+      cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_default_novalue_1
+      cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_default_novalue_n_1
+      cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_fill
+      cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_fill_n
+      cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::__uninitialized_move_if_noexcept_a
+      cmake_bindings/std/complex.cpp:#include <bits/stl_uninitialized.h> // std::uninitialized_copy
   
-The important information in the output is the ``std::`` types/functions without the leading underscores.
- Those are STL-implementation independent types/functions that should be defined elsewhere, not in the headers from the ``bits`` directory.
-In this particular example, the function of interest is ``std::uninitialized_copy``.  
+    The important information in the output is the ``std::`` types/functions without the leading underscores.
+    Those are STL-implementation independent types/functions that should be defined elsewhere, not in the headers from the ``bits`` directory.
+    In this particular example, the function of interest is ``std::uninitialized_copy``.  
 
-A quick search in the C++ documentation at https://en.cppreference.com or other resources tells that this function is defined in the <memory> header.
-Therefore, this information should be hardcoded into the binder.
+    A quick search in the C++ documentation at https://en.cppreference.com or other resources tells that this function is defined in the <memory> header.
+    Therefore, this information should be hardcoded into the binder.
 
 
 3.  The internal binder function that handles the STL library mappings is located in ``source/types.cpp``:``add_relevant_include_for_decl``.  
-Briefly, the function has a map with the STL headers and the types those contain. That should look similar to this:
+    Briefly, the function has a map with the STL headers and the types those contain. That should look similar to this:
 
-.. code-block:: python
+    .. code-block::  C++
 
-    { "<algorithm>", {"std::move_backward", "std::iter_swap", "std::min"} },
-    { "<exception>", {"std::nested_exception"} }
+      { "<algorithm>", {"std::move_backward", "std::iter_swap", "std::min"} },
+      { "<exception>", {"std::nested_exception"} }
 
 
-If there is a need to make a simple change, like in our case,  the map for the ``<memory>`` can be added like this:
+    If there is a need to make a simple change, like in our case,  the map for the ``<memory>`` can be added like this:
 
-.. code-block:: python
+    .. code-block::  C++
 
-    { "<algorithm>", {"std::move_backward", "std::iter_swap", "std::min"} },
-    { "<exception>", {"std::nested_exception"} },
-    { "<memory>", {"std::uninitialized_copy"} },
+      { "<algorithm>", {"std::move_backward", "std::iter_swap", "std::min"} },
+      { "<exception>", {"std::nested_exception"} },
+      { "<memory>", {"std::uninitialized_copy"} },
 
 
-In addition to that, to ensure a better portability, some of the implementation-specific headers are replaced in binder with the standard ones.
-The map that holds the replacements is located in the ``source/types.cpp`` file as well. It should look similar to this:
+    In addition to that, to ensure a better portability, some of the implementation-specific headers are replaced in binder with the standard ones.
+    The map that holds the replacements is located in the ``source/types.cpp`` file as well. It should look similar to this:
 
-.. code-block:: python
+    .. code-block::  C++
 
        static vector< std::pair<string, string> > const include_map = {
         make_pair("<bits/ios_base.h>",     "<ios>"),
@@ -115,4 +116,4 @@ The map that holds the replacements is located in the ``source/types.cpp`` file
     In some cases, many iterations of the described procedure will be needed till all the STL types/functions will be mapped to the correct includes. 
 
     If this fixes your problem please let us know, or make a pull request!
-    
+

documentation/examples.rst

@@ -36,20 +36,20 @@ folder.
 Their names are self explanatory, but I would highly recommend that for your
 own applications that you follow the ``python`` & ``cmake`` workflow.
 
-Each script's final running lines also imports the ``test_struct`` module and
-prints a variable or two of it to prove that it's working.
+Each script\'s final running lines also imports the ``test_struct`` module and
+prints a variable or two of it to prove that it is working.
 
 
 This example/tutorial will walk you through the step-by-step of both
 ``via_bash`` scripts, because they will help you better understand what needs
 to be done to generate bindings.  Upon understanding the more manual ``bash``
 method, the ``cmake`` code should make much more sense.
 
-The rest of "Simple struct" will also take you through generating pybind11 stl
+The rest of \"Simple struct\" will also take you through generating pybind11 stl
 bindings (like making bindings for `std::vector` -> python list) and how to use
-binder's bindings for `std::vector` to access `std::vector` objects without
+binder\'s bindings for `std::vector` to access `std::vector` objects without
 converting them to python lists.  This allows us to benefit from the speed of
-c++!
+C++!
 
 
 Building bindings basics
@@ -191,18 +191,18 @@ You may notice how ever that this will still fail:
 
     python3 -c "import sys; sys.path.append('.'); import test_struct; f = test_struct.testers.test_my_struct(); print(f.a_float); f.add_float(); print(f.a_float); print(f.a_vector)"
 
-This fails because python doesn't understand how to interact with the std
+This fails because python does not understand how to interact with the std
 library classes like ``std::vector``. You can get around this by remaking your
 bindings with this config file. **However**, you must note that when you are
 returning vectors into your python environment, or pushing lists to the c++
-side, there is a performance penalty when pybind converts from ``python
+side, there is a performance penalty when pybind11 converts from ``python
 list[]`` -> ``std::vector``, and vice-versa. This can be a problem when dealing
 with larger lists/vectors.
 
 If performance is critical, it is advised that most work is done via c++,
-and you just use python as the 'glue'. For example, the following command
-doesn't fail, because python never has to 'see' the std::vector and all of
-the work is done in the c++ layer.
+and you just use python as the \"glue\". For example, the following command
+does not fail, because python never has to \"see\" the std::vector and all of
+the work is done in the C++ layer.
 
 .. code-block:: console