documentation improvements

docs/source/api/as_args.rst

@@ -17,6 +17,7 @@ as_args
 
 .. literalinclude:: ../../../examples/source/args_from_container.cpp
 	:caption: args_from_container.cpp
+	:name: args-from-container
 	:linenos:
 
 It is basically implemented as a `one-way customization point`_. For more information about customization points, see the :doc:`tutorial on how to customize sol to work with your types<../tutorial/customization>`.

docs/source/api/coroutine.rst

@@ -11,6 +11,7 @@ For example, you can work with a coroutine like this:
 
 .. code-block:: lua
     :caption: co.lua
+    :name: co-lua
 
         function loop()
             while counter ~= 30
@@ -25,6 +26,7 @@ This is a function that yields:
 
 .. code-block:: cpp
     :caption: main.cpp
+    :name: yield-main
 
     sol::state lua;
     lua.open_libraries(sol::lib::base, sol::lib::coroutine);
@@ -43,6 +45,7 @@ Note that this code doesn't check for errors: to do so, you can call the functio
 
 .. code-block:: cpp
     :caption: main_with_thread.cpp
+    :name: yield-main-thread
 
     sol::state lua;
     lua.open_libraries(sol::lib::base, sol::lib::coroutine);
@@ -63,6 +66,7 @@ members
 
 .. code-block:: cpp
     :caption: function: constructor
+    :name: sol-coroutine-constructor
 
     coroutine(lua_State* L, int index = -1);
 
@@ -70,7 +74,7 @@ Grabs the coroutine at the specified index given a ``lua_State*``.
 
 .. code-block:: cpp
 	:caption: returning the coroutine's status
-	:name: status
+    :name: sol-coroutine-status
 
 	call_status status() const noexcept;
 
@@ -79,6 +83,7 @@ Returns the status of a coroutine.
 
 .. code-block:: cpp
 	:caption: checks for an error
+    :name: sol-coroutine-error
 
 	bool error() const noexcept;
 
@@ -88,6 +93,7 @@ Checks if an error occured when the coroutine was run.
 
 .. code-block:: cpp
 	:caption: runnable and explicit operator bool
+    :name: sol-coroutine-runnable
 
 	bool runnable () const noexcept;
 	explicit operator bool() const noexcept;
@@ -96,6 +102,7 @@ These functions allow you to check if a coroutine can still be called (has more
 
 .. code-block:: cpp
 	:caption: calling a coroutine
+    :name: sol-coroutine-operator-call
 
 	template<typename... Args>
 	protected_function_result operator()( Args&&... args );

docs/source/api/environment.rst

@@ -5,6 +5,7 @@ environment
 
 .. code-block:: cpp
 	:caption: environment
+	:name: sol-environment
 
 	class environment : public table;
 
@@ -32,6 +33,7 @@ free functions
 
 .. code-block:: cpp
 	:caption: function: set_environment
+	:name: sol-environment-set_environment
 
 	template <typename T>
 	void set_environment( const environment& env, const T& target );
@@ -41,6 +43,7 @@ See :ref:`environment::set_on<environment-set-on>`.
 
 .. code-block:: cpp
 	:caption: function: get_environment
+	:name: sol-environment-set_environment
 
 	template <typename E = reference, typename T>
 	basic_environment<E> get_environment( const T& target );
@@ -53,6 +56,7 @@ members
 
 .. code-block:: cpp
 	:caption: constructor: environment
+	:name: sol-environment-constructor
 
 	environment(lua_State* L, sol::new_table nt);
 	environment(lua_State* L, sol::new_table nt, const sol::reference& fallback);
@@ -68,7 +72,7 @@ The second and third unique constructors take a special empty type that serves a
 
 .. code-block:: cpp
 	:caption: function: set_on
-	:name: environment-set-on
+	:name: sol-environment-set_on
 	
 	template <typename T>
 	void set_on(const T& target);

docs/source/api/function.rst

@@ -16,6 +16,7 @@ Function is a correct-assuming version of :doc:`protected_function<protected_fun
 
 .. code-block:: cpp
 	:caption: constructor: unsafe_function
+	:name: sol-function-constructor
 
 	unsafe_function(lua_State* L, int index = -1);
 
@@ -24,12 +25,15 @@ Calls the constructor and creates this type, straight from the stack. For exampl
 
 .. literalinclude:: ../../../examples/source/tie.cpp
 	:caption: funcs.lua
+	:name: function-eg-tie-lua
 	:lines: 9-13
 	:linenos:
 
 The following C++ code will call this function from this file and retrieve the return value:
 
 .. literalinclude:: ../../../examples/source/tie.cpp
+	:caption: tie.cpp
+	:name: function-eg-tie-0
 	:lines: 1-7,16-22
 	:linenos:
 
@@ -38,6 +42,8 @@ The call ``woof(20)`` generates a :ref:`unsafe_function_result<unsafe-function-r
 You can also return multiple values by using ``std::tuple``, or if you need to bind them to pre-existing variables use ``sol::tie``:
 
 .. literalinclude:: ../../../examples/source/tie.cpp
+	:caption: tie.cpp
+	:name: function-eg-tie-1
 	:lines: 24-
 	:linenos:
 
@@ -51,6 +57,7 @@ This makes it much easier to work with multiple return values. Using ``std::tie`
 
 .. code-block:: cpp
 	:caption: function: call operator / function call
+	:name: sol-function-operator-call
 
 	template<typename... Args>
 	unsafe_function_result operator()( Args&&... args );

docs/source/api/metatable_key.rst

@@ -12,4 +12,5 @@ You can use this in conjunction with :doc:`sol::table<table>` to set/get a metat
 
 .. literalinclude:: ../../../examples/source/metatable_key_low_level.cpp
 	:caption: messing with metatables
+	:name: sol-metatable_key-eg
 	:linenos:

docs/source/api/new_table.rst

@@ -16,6 +16,7 @@ members
 
 .. code-block:: cpp
 	:caption: constructor: new_table
+	:name: sol-new_table-constructor
 
 	new_table(int sequence_hint = 0, int map_hint = 0);
 	

docs/source/tutorial/customization.rst

@@ -7,6 +7,7 @@ These are template class/structs, so you'll override them using a technique C++
 
 .. literalinclude:: ../../../examples/source/customization_multiple.cpp
 	:name: customization-overriding
+	:caption: main.cpp
 	:linenos:
 	:lines: 1-52
 
@@ -14,6 +15,7 @@ This is the base formula that you can follow to extend to your own classes. Usin
 
 .. literalinclude:: ../../../examples/source/customization_multiple.cpp
 	:name: customization-overriding-use
+	:caption: main.cpp
 	:linenos:
 	:lines: 52-
 

docs/source/tutorial/cxx-in-lua.rst

@@ -7,6 +7,7 @@ Take this ``player`` struct in C++ in a header file:
 
 .. literalinclude:: ../../../examples/source/usertype_advanced.cpp
 	:caption: player.hpp
+	:name: tutorial-player-class
 	:linenos:
 	:lines: 8-51
 
@@ -14,6 +15,7 @@ It's a fairly minimal class, but we don't want to have to rewrite this with meta
 
 .. literalinclude:: ../../../examples/source/usertype_advanced.cpp
 	:caption: player_script.lua
+	:name: tutorial-player-script
 	:language: lua
 	:linenos:
 	:lines: 97-127
@@ -22,6 +24,7 @@ To do this, you bind things using the ``new_usertype`` and method as shown below
 
 .. literalinclude:: ../../../examples/source/usertype_advanced.cpp
 	:caption: main.cpp
+	:name: tutorial-player-usertype
 	:language: cpp
 	:linenos:
 	:lines: 1-3,5,7-9,53,55-85,135-136,143-
@@ -30,6 +33,7 @@ There is one more method used in the script that is not in C++ or defined on the
 
 .. literalinclude:: ../../../examples/source/usertype_advanced.cpp
 	:caption: prelude_script.lua
+	:name: tutorial-prelude-script
 	:language: lua
 	:linenos:
 	:lines: 89-92

docs/source/tutorial/getting-started.rst

@@ -14,6 +14,7 @@ When you're ready, try compiling this short snippet:
 .. literalinclude:: ../../../examples/source/tutorials/first_snippet.cpp
 	:linenos:
 	:caption: hello_lua.cpp
+	:name: hello-lua
 
 Using this simple command line:
 
@@ -32,6 +33,7 @@ The second line opens a single lua-provided library, "base". There are several o
 .. literalinclude:: ../../../examples/source/tutorials/open_multiple_libraries.cpp
 	:linenos:
 	:caption: multiple_libraries.cpp
+	:name: open-multiple-libraries
 
 If you're interested in integrating sol with a project that already uses some other library or Lua in the codebase, check out the :doc:`existing example<existing>` to see how to work with sol when you add it to a project (the existing example covers ``require`` as well)!
 

docs/source/tutorial/ownership.rst

@@ -25,6 +25,7 @@ sol will not take ownership of raw pointers: raw pointers do not own anything. s
 .. literalinclude:: ../../../examples/source/tutorials/pointer_lifetime.cpp
 	:linenos:
 	:caption: pointer_lifetime.cpp
+	:name: pointer-lifetime-raw-ptr
 	:lines: 1-11,14-22, 74-
 
 Use/return a ``unique_ptr`` or ``shared_ptr`` instead or just return a value:
@@ -32,6 +33,7 @@ Use/return a ``unique_ptr`` or ``shared_ptr`` instead or just return a value:
 .. literalinclude:: ../../../examples/source/tutorials/pointer_lifetime.cpp
 	:linenos:
 	:caption: (smart pointers) pointer_lifetime.cpp
+	:name: pointer-lifetime-smart-ptr
 	:lines: 1-11,14-22, 74-
 
 If you have something you know is going to last and you just want to give it to Lua as a reference, then it's fine too:
@@ -39,6 +41,7 @@ If you have something you know is going to last and you just want to give it to
 .. literalinclude:: ../../../examples/source/tutorials/pointer_lifetime.cpp
 	:linenos:
 	:caption: (static) pointer_lifetime.cpp
+	:name: pointer-lifetime-static
 	:lines: 1-11,46-49,74-
 
 
@@ -47,6 +50,7 @@ sol can detect ``nullptr``, so if you happen to return it there won't be any dan
 .. literalinclude:: ../../../examples/source/tutorials/pointer_lifetime.cpp
 	:linenos:
 	:caption: (nil/nullptr) pointer_lifetime.cpp
+	:name: pointer-lifetime-nil
 	:lines: 1-11,51-