doc: Make docs buildable with sphinx.

.gitignore

@@ -4,4 +4,5 @@ doc/*.html
 doc/version.rst
 nppBackup/
 build/
+_build/
 *.kdev4

doc/build-options.rst

@@ -1,3 +1,5 @@
+.. _part-build-options:
+
 Build options
 =============
 
@@ -65,7 +67,7 @@ LUABIND_DYNAMIC_LINK
 
 LUABIND_NO_RTTI
     You can define this if you don't want luabind to use ``dynamic_cast<>``.
-    It will disable `Object identity`_.
+    It will disable :ref:`sec-objid`.
 
 NDEBUG
     This define will disable all asserts and should be defined in a release 

doc/classes.rst

@@ -1,3 +1,5 @@
+.. _part-classes:
+
 Binding classes to Lua
 ======================
 
@@ -95,6 +97,8 @@ This selects the first overload of the function ``f`` to bind. The second
 overload is not bound.
 
 
+.. _sec-properties:
+
 Properties
 ----------
 
@@ -450,6 +454,7 @@ Like this:
 Internally, luabind will do the necessary conversions on the raw pointers, which
 are first extracted from the holder type.
 
+.. _sec-split-cls-registration:
 
 Splitting class registrations
 -----------------------------
@@ -484,4 +489,4 @@ Here, the class ``X`` is registered in two steps. The two functions
 units.
 
 To separate the module registration and the classes to be registered, see
-`Splitting up the registration`_.
+:ref:`part-split-registration`.

doc/conf.py

@@ -64,7 +64,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = ['_build', 'policies']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -93,6 +93,10 @@
 
 highlight_language = 'c++'
 
+rst_epilog = """
+.. |...| unicode:: U+02026
+"""
+
 
 # -- Options for HTML output ---------------------------------------------------
 

doc/errors.rst

@@ -1,6 +1,8 @@
 Error Handling
 ==============
 
+.. _sec-pcall-errorfunc:
+
 pcall errorfunc
 ---------------
 
@@ -69,6 +71,8 @@ Note that the callback set by ``set_pcall_callback()`` will only be used when
 luabind executes lua code. Anytime when you call ``lua_pcall`` yourself, you
 have to supply your function if you want error messages translated.
 
+.. _sec-lua-panic:
+
 lua panic
 ---------
 
@@ -130,7 +134,7 @@ in-depth explanation.
 
   There is no data member named *attribute-name* in the class *class-name*,
   or there's no setter-function registered on that property name. See the 
-  Properties_ section.
+  :ref:`sec-properties` section.
 
 - .. parsed-literal:: 
 
@@ -146,7 +150,7 @@ in-depth explanation.
 
   The class' constructor or member function threw an unknown exception.
   Known exceptions are const char*, std::exception. See the 
-  `exceptions`_ section.
+  :ref:`part-exceptions` section.
 
 - .. parsed-literal::
 

doc/exceptions.rst

@@ -1,3 +1,5 @@
+.. _part-exceptions:
+
 Exceptions
 ==========
 

doc/faq.rst

@@ -15,8 +15,8 @@ What's wrong with functions taking variable number of arguments?
 Internal structure overflow in VC
     If you, in visual studio, get fatal error C1204: compiler limit :
     internal structure overflow. You should try to split that compilation
-    unit up in smaller ones. See `Splitting up the registration`_ and
-    `Splitting class registrations`_.
+    unit up in smaller ones. See :ref:`part-split-registration` and
+    :ref:`sec-split-cls-registration`.
 
 What's wrong with precompiled headers in VC?
     Visual Studio doesn't like anonymous namespaces in its precompiled
@@ -85,4 +85,5 @@ Crashes when linking against luabind as a dll in Windows
 
 I cannot register a function with a non-const parameter
     This is because there is no way to get a reference to a Lua value. Have 
-    a look at out_value_ and pure_out_value_ policies.
+    a look at :ref:`policy-out_value` and :ref:`policy-pure_out_value`
+    policies.

doc/functions.rst

@@ -1,3 +1,5 @@
+.. _part-functions:
+
 Binding functions to Lua
 ========================
 
@@ -11,7 +13,7 @@ following synopsis::
 - F is the function pointer you want to register. 
 - The Policies parameter is used to describe how parameters and return values 
   are treated by the function, this is an optional parameter. More on this in 
-  the `policies`_ section.
+  the :ref:`part-policies` section.
 
 An example usage could be if you want to register the function ``float
 std::sin(float)``::
@@ -56,7 +58,7 @@ isn't.
 .. sidebar:: Ownership transfer
 
    To correctly handle ownership transfer, create_a() would need an adopt
-   return value policy. More on this in the `Policies`_ section.
+   return value policy. More on this in the :ref:`part-policies` section.
 
 For example, if the following function and class is registered:
 
@@ -137,7 +139,7 @@ Like this::
 
 
 If you want to use a custom error handler for the function call, see
-``set_pcall_callback`` under `pcall errorfunc`_.
+``set_pcall_callback`` under :ref:`sec-pcall-errorfunc`.
 
 Using Lua threads
 -----------------
@@ -167,10 +169,11 @@ value passed in to ``lua_yield()``. When you want to continue the execution, you
 it one. The parameters to ``resume()`` will be returned by ``yield()`` on the Lua side.
 
 For yielding C++-functions (without the support of passing data back and forth between the
-Lua side and the c++ side), you can use the yield_ policy.
+Lua side and the c++ side), you can use the :ref:`policy-yield` policy.
 
-With the overload of ``resume_function`` that takes an object_, it is important that the
-object was constructed with the thread as its ``lua_State*``. Like this:
+With the overload of ``resume_function`` that takes an :ref:`part-object`,
+it is important that the object was constructed with the thread as its
+``lua_State*``. Like this:
 
 .. parsed-literal::
 

doc/index.rst

@@ -11,12 +11,29 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   intro
+   building
+   basic-usage
+   scopes
+   functions
+   classes
+   userdefined-converters
+   object
+   lua-classes
+   exceptions
+   policies
+   split-registration
+   errors
+   build-options
+   impl-notes
+   faq
+   issues
+   acknowledgments
 
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
 

doc/lua-classes.rst

@@ -141,6 +141,8 @@ take a ``lua_State`` pointer, and the name is a member function in the Lua class
 	virtual function where the only difference in their signatures is their constness, the
 	wrong overload will be called by ``call_member``. This is rarely the case though.
 
+.. _sec-objid:
+
 Object identity
 ~~~~~~~~~~~~~~~
 

doc/object.rst

@@ -1,3 +1,5 @@
+.. _part-object:
+
 Object
 ======
 
@@ -66,7 +68,7 @@ reading and writing values into the table (using operator=).
 Note that it is impossible to know if a Lua value is indexable or not
 (``lua_gettable`` doesn't fail, it succeeds or crashes). This means that if
 you're trying to index something that cannot be indexed, you're on your own.
-Lua will call its ``panic()`` function. See `lua panic`_.
+Lua will call its ``panic()`` function. See :ref:`sec-lua-panic`.
 
 There are also free functions that can be used for indexing the table, see
 `Related functions`_.
@@ -258,10 +260,10 @@ true value of the table entry.
 The ``object_cast`` function casts the value of an object to a C++ value.
 You can supply a policy to handle the conversion from lua to C++. If the cast
 cannot be made a ``cast_failed`` exception will be thrown. If you have
-defined LUABIND_NO_ERROR_CHECKING (see `Build options`_) no checking will occur,
-and if the cast is invalid the application may very well crash. The nothrow
-versions will return an uninitialized ``boost::optional<T>`` object, to
-indicate that the cast could not be performed.
+defined LUABIND_NO_ERROR_CHECKING (see :ref:`part-build-options`) no checking
+will occur, and if the cast is invalid the application may very well crash.
+The nothrow versions will return an uninitialized ``boost::optional<T>``
+object, to indicate that the cast could not be performed.
 
 The function signatures of all of the above functions are really templates
 for the object parameter, but the intention is that you should only pass

doc/policies.rst

@@ -1,3 +1,5 @@
+.. _part-policies:
+
 Policies
 ========
 
@@ -11,16 +13,16 @@ to the ``this`` pointer.
     :local:
     :depth: 1
 
-.. include:: adopt.rst
-.. include:: dependency.rst
-.. include:: out_value.rst
-.. include:: pure_out_value.rst
-.. include:: return_reference_to.rst
-.. include:: copy.rst
-.. include:: discard_result.rst
-.. include:: return_stl_iterator.rst
-.. include:: raw.rst
-.. include:: yield.rst
+.. include:: policies/adopt.rst
+.. include:: policies/dependency.rst
+.. include:: policies/out_value.rst
+.. include:: policies/pure_out_value.rst
+.. include:: policies/return_reference_to.rst
+.. include:: policies/copy.rst
+.. include:: policies/discard_result.rst
+.. include:: policies/return_stl_iterator.rst
+.. include:: policies/raw.rst
+.. include:: policies/yield.rst
 
 ..  old policies section
     ===================================================

doc/policies/out_value.rst

@@ -1,3 +1,5 @@
+.. _policy-out_value:
+
 out_value
 ----------------
 

doc/policies/pure_out_value.rst

@@ -1,3 +1,5 @@
+.. _policy-pure_out_value:
+
 pure_out_value
 ----------------
 

doc/policies/yield.rst

@@ -1,3 +1,5 @@
+.. _policy-yield:
+
 yield
 ----------------
 

doc/scopes.rst

@@ -66,8 +66,8 @@ Each declaration must be separated by a comma, like this::
     ];
 
 
-More about the actual declarations in the `Binding functions to Lua`_ and
-`Binding classes to Lua`_ sections.
+More about the actual declarations in the :ref:`part-functions` and
+:ref:`part-classes` sections.
 
 A word of caution, if you are in really bad need for performance, putting your
 functions in tables will increase the lookup time.

doc/split-registration.rst

@@ -1,3 +1,5 @@
+.. _part-split-registration:
+
 Splitting up the registration
 =============================