Improvements to the documentation formatting and internal links

12 files changed, 159 insertions, 126 deletions

diff --git a/docs/api/resources.rst b/docs/api/resources.rst
index 85059a2..54dd5bc 100644
--- a/docs/api/resources.rst
+++ b/docs/api/resources.rst
@@ -7,6 +7,17 @@ Resources are high level abstractions to managing specific sessions. An instance
 of one of these classes is returned by the :meth:`~pyvisa.highlevel.ResourceManager.open_resource`
 depending on the resource type.
 
+Generic classes
+~~~~~~~~~~~~~~~
+
+    - :class:`~pyvisa.resources.Resource`
+    - :class:`~pyvisa.resources.MessageBasedResource`
+    - :class:`~pyvisa.resources.RegisterBasedResource`
+
+
+Specific Classes
+~~~~~~~~~~~~~~~~
+
     - :class:`~pyvisa.resources.SerialInstrument`
     - :class:`~pyvisa.resources.TCPIPInstrument`
     - :class:`~pyvisa.resources.TCPIPSocket`
@@ -23,6 +34,26 @@ depending on the resource type.
 
 .. currentmodule::`pyvisa.resources`
 
+
+.. autoclass:: pyvisa.resources.Resource
+    :members:
+    :inherited-members:
+    :undoc-members:
+
+
+.. autoclass:: pyvisa.resources.MessageBasedResource
+    :members:
+    :inherited-members:
+    :exclude-members: ask_delay, ask_for_values, ask
+    :undoc-members:
+
+
+.. autoclass:: pyvisa.resources.RegisterBasedResource
+    :members:
+    :inherited-members:
+    :undoc-members:
+
+
 .. autoclass:: pyvisa.resources.SerialInstrument
     :members:
     :inherited-members:
diff --git a/docs/architecture.rst b/docs/architecture.rst
index fb2d82f..3402a05 100644
--- a/docs/architecture.rst
+++ b/docs/architecture.rst
@@ -13,7 +13,7 @@ PyVISA implements convenient and Pythonic programming in three layers:
     You will normally not need to access these functions directly. If you do,
     it probably means that we need to improve layer 2.
 
-    All level 1 functions are **static methods** of `VisaLibrary`.
+    All level 1 functions are **static methods** of :class:`pyvisa.highlevel.VisaLibrary`.
 
     .. warning:: Notice however that low-level functions might not be present in all backends.
                  For broader compatibility, do no use this layer. All the functionality should
@@ -30,47 +30,47 @@ PyVISA implements convenient and Pythonic programming in three layers:
     aspects of the VISA library which are not implemented by the corresponding
     resource class.
 
-    All level 2 functions are **bound methods** of `VisaLibrary`.
+    All level 2 functions are **bound methods** of :class:`pyvisa.highlevel.VisaLibrary`.
 
- 3. High-level: An object-oriented layer for `ResourceManager` and `Resource`
+ 3. High-level: An object-oriented layer for :class:`pyvisa.highlevel.ResourceManager` and :class:`pyvisa.resources.Resource`
 
-    The `ResourceManager` implements methods to inspect connected resources. You also
-    use this object to open other resources instantiating the appropriate `Resource`
+    The ``ResourceManager`` implements methods to inspect connected resources. You also
+    use this object to open other resources instantiating the appropriate ``Resource``
     derived classes.
 
-    `Resource` and the derived classes implement functions and attributes access
+    ``Resource`` and the derived classes implement functions and attributes access
     to the underlying resources in a Pythonic way.
 
-Most of the time you will only need to instantiate a `ResourceManager`. For a given resource,
-you will use the `open_resource` method to obtain the appropriate object. If needed, you will
-be able to access the `VisaLibrary` object directly using the `visalib` attribute.
+Most of the time you will only need to instantiate a ``ResourceManager``. For a given resource,
+you will use the :meth:`pyvisa.highlevel.ResourceManager.open_resource` method to obtain the appropriate object. If needed, you will
+be able to access the ``VisaLibrary`` object directly using the :attr:`pyvisa.highlevel.ResourceManager.visalib` attribute.
 
-The `VisaLibrary` does the low-level calls. In the default NI Backend, levels 1 and 2 are
-implemented in the same package called `ctwrapper` (which stands for ctypes wrapper).
+The ``VisaLibrary`` does the low-level calls. In the default NI Backend, levels 1 and 2 are
+implemented in the same package called :mod:`pyvisa.ctwrapper` (which stands for ctypes wrapper).
 This package is included in PyVISA.
 
-Other backends can be used just by passing the name of the backend to `ResourceManager`
+Other backends can be used just by passing the name of the backend to ``ResourceManager``
 after the `@` symbol. See more information in :ref:`backends`.
 
 
 Calling middle- and low-level functions
 ---------------------------------------
 
-After you have instantiated the `ResourceManager`::
+After you have instantiated the ``ResourceManager``::
 
     >>> import visa
     >>> rm = visa.ResourceManager()
 
-you can access the corresponding `VisaLibrary` instance under the `visalib` attribute.
+you can access the corresponding ``VisaLibrary`` instance under the ``visalib`` attribute.
 
-As an example, consider the VISA function `viMapAddress`. It appears in the low-level
-layer as the static method `viMapAddress` of `visalib` attributed and also appears
-in the middle-level layer as `map_address`.
+As an example, consider the VISA function ``viMapAddress``. It appears in the low-level
+layer as the static method ``viMapAddress`` of ``visalib`` attributed and also appears
+in the middle-level layer as ``map_address``.
 
 You can recognize low and middle-level functions by their names. Low-level functions
-carry the same name as in the shared library, and they are prefixed by `vi`.
+carry the same name as in the shared library, and they are prefixed by **vi**.
 Middle-level functions have a friendlier, more pythonic but still recognizable name.
-Typically, camelCase names where stripped from the leading `vi` and changed to underscore
+Typically, camelCase names where stripped from the leading **vi** and changed to underscore
 separated lower case names. The docs about these methods is located here :ref:`api`.
 
 
@@ -83,7 +83,7 @@ for example::
     >>> rm.visalib.viMapAddress(<here goes the arguments>)
 
 To call this functions you need to know the function declaration and how to
-interface it to python. To help you out, the `VisaLibrary` object also contains
+interface it to python. To help you out, the ``VisaLibrary`` object also contains
 middle-level functions.
 
 It is very likely that you will need to access the VISA constants using these methods.
@@ -93,7 +93,7 @@ You can find the information about these constants here :ref:`api_constants`
 Middle-level
 ~~~~~~~~~~~~
 
-The `VisaLibrary` object exposes the middle-level functions which are
+The ``VisaLibrary`` object exposes the middle-level functions which are
 one-to-one mapped from the foreign library as bound methods.
 
 Each middle-level function wraps one low-level function.
diff --git a/docs/backends.rst b/docs/backends.rst
index e94188e..1aded42 100644
--- a/docs/backends.rst
+++ b/docs/backends.rst
@@ -14,10 +14,10 @@ their programs to use other packages with different API.
 Since 1.6, PyVISA is a frontend to VISA. It provides a nice, Pythonic API and can
 connect to multiple backends. Each backend exposes a class derived from VisaLibraryBase
 that implements the low-level communication. The ctypes wrapper around NI-VISA is the
-default backend (called `ni`) and is bundled with PyVISA for simplicity.
+default backend (called **ni**) and is bundled with PyVISA for simplicity.
 
 You can specify the backend to use when you instantiate the resource manager using the
-`@` symbol. Remembering that `ni` is the default, this::
+``@`` symbol. Remembering that **ni** is the default, this::
 
     >>> import visa
     >>> rm = visa.ResourceManager()
@@ -32,7 +32,7 @@ You can still provide the path to the library if needed::
     >>> import visa
     >>> rm = visa.ResourceManager('/path/to/lib@ni')
 
-Under the hood, the `ResourceManager` looks for the requested backend and instantiate
+Under the hood, the :class:`pyvisa.highlevel.ResourceManager` looks for the requested backend and instantiate
 the VISA library that it provides.
 
 PyVISA locates backends by name. If you do:
@@ -40,7 +40,7 @@ PyVISA locates backends by name. If you do:
     >>> import visa
     >>> rm = visa.ResourceManager('@somename')
 
-PyVISA will try to import a package/module named `pyvisa-somename` which should be
+PyVISA will try to import a package/module named ``pyvisa-somename`` which should be
 installed in your system. This is a loosly coupled configuration free method.
 PyVISA does not need to know about any backend out there until you actually
 try to use it.
@@ -63,7 +63,7 @@ What does a minimum backend looks like? Quite simple::
     WRAPPER_CLASS = MyLibrary
 
 Additionally you can provide a staticmethod named get_debug_info` that should return a
-dictionary of debug information which is printed when you call `python -m visa info`
+dictionary of debug information which is printed when you call ``python -m visa info``
 
 An important aspect of developing a backend is knowing which VisaLibraryBase method to
 implement and what API to expose.
@@ -95,7 +95,7 @@ If you need to start sending bytes to MessageBased instruments you will require:
 For other usages or devices, you might need to implement other functions. Is really up to you
 and your needs.
 
-These functions should raise a `VisaIOError` or emit a `VisaIOWarning` if necessary.
+These functions should raise a :class:`pyvisa.errors.VisaIOError` or emit a :class:`pyvisa.errors.VisaIOWarning` if necessary.
 
 
 Complete list of level 2 functions to implement::
diff --git a/docs/configuring.rst b/docs/configuring.rst
index c819c2b..ddba398 100644
--- a/docs/configuring.rst
+++ b/docs/configuring.rst
@@ -10,7 +10,7 @@ Configuring the NI backend
 
 In most cases PyVISA will be able to find the location of the shared visa library.
 If this does not work or you want to use another one, you need to provide the library
-path to the `ResourceManager` constructor::
+path to the :class:`pyvisa.highlevel.ResourceManager` constructor::
 
     >>> rm = ResourceManager('Path to library')
 
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 904fb71..0291f11 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -50,7 +50,7 @@ Contributing to an existing backend
 
 Backends are the central piece of PyVISA as they provide the low level communication
 over the different interfaces. There a couple of backends in the wild which can use
-your help. Look them up in PyPI_ (try `pyvisa` in the search box) and see where you
+your help. Look them up in PyPI_ (try `pyvisa``` in the search box) and see where you
 can help.
 
 
diff --git a/docs/faq.rst b/docs/faq.rst
index f4e0d5b..b07f6d6 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -61,7 +61,7 @@ Error: Could not found VISA library
 
 This error occurs when you have not provided a path for the VISA library and PyVISA
 is not able to find it for you. You can solve it by providing the library path to the
-`VisaLibrary` or `ResourceManager` constructor::
+``VisaLibrary`` or ``ResourceManager`` constructor::
 
     >>> visalib = VisaLibrary('/path/to/library')
 
@@ -105,7 +105,7 @@ The solution is to:
 
   1. Install and use a VISA library matching your Python 'bitness'
 
-     Download and install it from `National Instruments's VISA`. Run the debug
+     Download and install it from **National Instruments's VISA**. Run the debug
      command again to see if the new library was found by PyVISA. If not,
      create a configuration file as described in :ref:`configuring`.
 
diff --git a/docs/migrating.rst b/docs/migrating.rst
index edd0f8b..761e81a 100644
--- a/docs/migrating.rst
+++ b/docs/migrating.rst
@@ -9,7 +9,7 @@ Migrating from PyVISA < 1.5
           PyVISA 1.6+ introduces a few compatibility breaks.
 
 
-Some of these decisions were inspired by the `visalib` package as a part of Lantz_
+Some of these decisions were inspired by the ``visalib`` package as a part of Lantz_
 
 
 Short summary
@@ -103,10 +103,10 @@ As you see, most of the code shown above is making a few things explict.
 It adds 1 line of code (instantiating the ResourceManager object)
 which is not a big deal but it makes things cleaner.
 
-If you were using `printf`, `queryf`, `scanf`, `sprintf` or `sscanf` of `vpp43`,
+If you were using ``printf``, ``queryf``, ``scanf``, ``sprintf`` or ``sscanf`` of ``vpp43``,
 rewrite as pure Python code (see below).
 
-If you were using `Instrument.delay`, change your code or use `Instrument.query_delay`
+If you were using ``Instrument.delay``, change your code or use ``Instrument.query_delay``
 (see below).
 
 
@@ -124,8 +124,8 @@ A more detailed description
 Dropped support for string related functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The VISA library includes functions to search and manipulate strings such as `printf`,
-`queryf`, `scanf`, `sprintf` and `sscanf`. This makes sense as VISA involves a lot of
+The VISA library includes functions to search and manipulate strings such as ``printf``,
+``queryf``, ``scanf``, ``sprintf`` and ``sscanf``. This makes sense as VISA involves a lot of
 string handling operations. The original PyVISA implementation wrapped these functions.
 But these operations are easily expressed in pure python and therefore were rarely used.
 
@@ -137,16 +137,16 @@ We suggest that you replace such functions by a pure Python version.
 Isolated low-level wrapping module
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In the original PyVISA implementation, the low level implementation (`vpp43`) was
+In the original PyVISA implementation, the low level implementation (``vpp43``) was
 mixed with higher level constructs. The VISA library was wrapped using ctypes.
 
-In 1.5, we refactored it as `ctwrapper`. This allows us to test the
+In 1.5, we refactored it as ``ctwrapper``. This allows us to test the
 foreign function calls by isolating them from higher level abstractions.
 More importantly, it also allows us to build new low level modules that
-can be used as drop in replacements for `ctwrapper` in high level modules.
+can be used as drop in replacements for ``ctwrapper`` in high level modules.
 
-In 1.6, we made the `ResourceManager` the object exposed to the user. The type of the
-`VisaLibrary` can selected depending of the `library_path` and obtained from a plugin
+In 1.6, we made the ``ResourceManager`` the object exposed to the user. The type of the
+``VisaLibrary`` can selected depending of the ``library_path`` and obtained from a plugin
 package.
 
 We have two of such packages planned:
@@ -157,13 +157,13 @@ We have two of such packages planned:
 - a CFFI based wrapper. CFFI is new python package that allows easier and more
   robust wrapping of foreign libraries. It might be part of Python in the future.
 
-PyVISA 1.5 keeps `vpp43` in the legacy subpackage (reimplemented on top of `ctwrapper`)
+PyVISA 1.5 keeps ``vpp43`` in the legacy subpackage (reimplemented on top of ``ctwrapper``)
 to help with the migration. This module is gone in 1.6.
 
-All functions that were present in `vpp43` are now present in `ctwrapper` but they
+All functions that were present in ``vpp43`` are now present in ``ctwrapper`` but they
 take an additional first parameter: the foreign library wrapper.
 
-We suggest that you replace `vpp43` by accessing the `VisaLibrary` object under the attribute
+We suggest that you replace ``vpp43`` by accessing the ``VisaLibrary`` object under the attribute
 visalib of the resource manager which provides all foreign functions as bound methods (see below).
 
 
@@ -171,19 +171,19 @@ No singleton objects
 ~~~~~~~~~~~~~~~~~~~~
 
 The original PyVISA implementation relied on a singleton, global objects for the
-library wrapper (named `visa_library`, an instance of the old `pyvisa.vpp43.VisaLibrary`)
-and the resource manager (named `resource_manager`, and instance of the old
-`pyvisa.visa.ResourceManager`). These were instantiated on import and the user
-could rebind to a different library using the `load_library` method. Calling this
-method however did not affect `resource_manager` and might lead to an inconsistent
+library wrapper (named ``visa_library``, an instance of the old ``pyvisa.vpp43.VisaLibrary``)
+and the resource manager (named ``resource_manager``, and instance of the old
+``pyvisa.visa.ResourceManager``). These were instantiated on import and the user
+could rebind to a different library using the ``load_library`` method. Calling this
+method however did not affect ``resource_manager`` and might lead to an inconsistent
 state.
 
-There were additionally a few global structures such a `status` which stored the last
+There were additionally a few global structures such a ``status`` which stored the last
 status returned by the library and the warning context to prevent unwanted warnings.
 
-In 1.5, there is a new `VisaLibrary` class and a new `ResourceManager` class (they are
-both in `pyvisa.highlevel`). The new classes are not singletons, at least not in the
-strict sense. Multiple instances of `VisaLibrary` and `ResourceManager` are possible,
+In 1.5, there is a new ``VisaLibrary`` class and a new ``ResourceManager`` class (they are
+both in ``pyvisa.highlevel``). The new classes are not singletons, at least not in the
+strict sense. Multiple instances of ``VisaLibrary`` and ``ResourceManager`` are possible,
 but only if they refer to different foreign libraries. In code, this means:
 
     >>> lib1 = visa.VisaLibrary("/path/to/my/libvisa.so.7")
@@ -194,7 +194,7 @@ but only if they refer to different foreign libraries. In code, this means:
     >>> lib1 is lib3
     False
 
-Most of the time, you will not need access to a `VisaLibrary` object but to a `ResourceManager`.
+Most of the time, you will not need access to a ``VisaLibrary`` object but to a ``ResourceManager``.
 You can do:
 
     >>> lib = visa.VisaLibrary("/path/to/my/libvisa.so.7")
@@ -208,7 +208,7 @@ or equivalently:
           the user settings file (if exists) or guessed from the OS.
 
 In 1.6, the state returned by the library is stored per resource. Additionally,
-warnings can be silenced by resource as well. You can access with the `last_status`
+warnings can be silenced by resource as well. You can access with the ``last_status``
 property.
 
 All together, these changes makes PyVISA thread safe.
@@ -217,11 +217,11 @@ All together, these changes makes PyVISA thread safe.
 VisaLibrary methods as way to call Visa functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In the original PyVISA implementation, the `VisaLibrary` class was just having
+In the original PyVISA implementation, the ``VisaLibrary`` class was just having
 a reference to the ctypes library and a few functions.
 
-In 1.5, we introduced a new `VisaLibrary` class (`pyvisa.highlevel`) which has 
-every single low level function defined in `ctwrapper` as bound methods. In code, 
+In 1.5, we introduced a new ``VisaLibrary`` class (``pyvisa.highlevel``) which has
+every single low level function defined in ``ctwrapper`` as bound methods. In code,
 this means that you can do::
 
     >>> import visa
@@ -243,13 +243,13 @@ method. In code, this means that you can do::
 Ask vs. query
 ~~~~~~~~~~~~~
 
-Historically, the method `ask` has been used in PyVISA to do a `write` followed
-by a `read`. But in many other programs this operation is called `query`. Thereby
+Historically, the method ``ask`` has been used in PyVISA to do a ``write`` followed
+by a ``read``. But in many other programs this operation is called ``query``. Thereby
 we have decided to switch the name, keeping an alias to help with the transition.
 
-However, `ask_for_values` has not been aliased to `query_values` because the API
-is different. `ask_for_values` still uses the old formatting API which is limited
-and broken. We suggest that you migrate everything to `query_values`
+However, ``ask_for_values`` has not been aliased to ``query_values`` because the API
+is different. ``ask_for_values`` still uses the old formatting API which is limited
+and broken. We suggest that you migrate everything to ``query_values``
 
 
 Seconds to milliseconds
@@ -265,28 +265,28 @@ VISA docs out there without extra cognitive effort.
 Removal of Instrument.delay and added Instrument.query_delay
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In the original PyVISA implementation, `Instrument` takes a `delay`
+In the original PyVISA implementation, ``Instrument`` takes a ``delay``
 argument that adds a pause after each write operation (This also can
-be changed using the `delay` attribute).
+be changed using the ``delay`` attribute).
 
-In PyVISA 1.6, `delay` is removed. Delays after write operations must
+In PyVISA 1.6, ``delay`` is removed. Delays after write operations must
 be added to the application code. Instead, a new attribute and argument
-`query_delay` is available. This allows you to pause between `write` and `read`
-operations inside `query`. Additionally, `query` takes an optional argument
-called `query` allowing you to change it for each method call.
+``query_delay`` is available. This allows you to pause between ``write` and ``read``
+operations inside ``query``. Additionally, ``query`` takes an optional argument
+called ``query`` allowing you to change it for each method call.
 
 
 Deprecated term_chars and automatic removal of CR + LF
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In the original PyVISA implementation, `Instrument` takes a `term_chars`
+In the original PyVISA implementation, ``Instrument`` takes a ``term_chars``
 argument to change at the read and write termination characters. If this
-argument is `None`, `CR + LF` is appended to each outgoing message and
+argument is ``None``, ``CR + LF`` is appended to each outgoing message and
 not expected for incoming messages (although removed if present).
 
-In PyVISA 1.6, `term_chars` is replaced by `read_termination` and
-`write_termination`. In this way, you can set independently the termination
-for each operation. Automatic removal of `CR + LF` is also gone in 1.6.
+In PyVISA 1.6, ``term_chars`` is replaced by ``read_termination` and
+``write_termination``. In this way, you can set independently the termination
+for each operation. Automatic removal of ``CR + LF`` is also gone in 1.6.
 
 
 
diff --git a/docs/names.rst b/docs/names.rst
index cea2085..22609b8 100644
--- a/docs/names.rst
+++ b/docs/names.rst
@@ -7,7 +7,7 @@ VISA resource names
 If you use the function :func:`open_resource`, you must tell this
 function the *VISA resource name* of the instrument you want to
 connect to.  Generally, it starts with the bus type, followed by a
-double colon `"::"`, followed by the number within the bus.  For
+double colon ``"::"``, followed by the number within the bus.  For
 example,
 
 .. code-block:: none
@@ -22,7 +22,7 @@ write
 
    GPIB1::10
 
-As for the bus, things like `"GPIB"`, `"USB"`, `"ASRL"` (for
+As for the bus, things like ``"GPIB"``, ``"USB"``, ``"ASRL"`` (for
 serial/parallel interface) are possible.  So for connecting to an
 instrument at COM2, the resource name is
 
@@ -32,11 +32,11 @@ instrument at COM2, the resource name is
 
 (Since only one instrument can be connected with one serial interface,
 there is no double colon parameter.)  However, most VISA systems allow
-aliases such as `"COM2"` or `"LPT1"`.  You may also add your own
+aliases such as ``"COM2"`` or ``"LPT1"``.  You may also add your own
 aliases.
 
 The resource name is case-insensitive.  It doesn't matter whether you
-say `"ASRL2"` or `"asrl2"`.  For further information, I have to refer
+say ``"ASRL2"`` or ``"asrl2"``.  For further information, I have to refer
 you to a comprehensive VISA description like
 `<http://www.ni.com/pdf/manuals/370423a.pdf>`_.
 
diff --git a/docs/resources.rst b/docs/resources.rst
index 8d9a2af..93a0211 100644
--- a/docs/resources.rst
+++ b/docs/resources.rst
@@ -9,8 +9,8 @@ types of resources (eg. GPIB, Serial). Each contains the particular set of
 attributes an methods that are available by the underlying device.
 
 You do not create this objects directly but they are returned by the
-`open_resource` method of a `ResourceManager`. In general terms, there
-are two main groups derived from `Resource`: `MessageBased` and `RegisterBased`.
+:meth:`pyvisa.highlevel.ResourceManager.open_resource` method of a :class:`pyvisa.highlevel.ResourceManager`. In general terms, there
+are two main groups derived from :class:`pyvisa.resources.Resource`, :class:`pyvisa.resources.RegisterBasedResource` and :class:`pyvisa.resources.RegisterBasedResource`.
 
 .. note:: The resource Python class to use is selected automatically from the
           resource name. However, you can force a Resource Python class:
@@ -19,8 +19,8 @@ are two main groups derived from `Resource`: `MessageBased` and `RegisterBased`.
           >>> inst = rm.open('ASRL1::INSTR', resource_pyclass=MessageBasedResource)
 
 
-The following sections explore the most common attributes of `Resource` and
-`MessageBased` (Serial, GPIB, etc) which are the ones you will encounte more
+The following sections explore the most common attributes of ``Resource`` and
+``MessageBased`` (Serial, GPIB, etc) which are the ones you will encounte more
 often. For more information, refer to the :ref:`api`.
 
 
@@ -134,10 +134,10 @@ Alternatively you can give it when creating your instrument object::
    my_instrument = rm.open_resource("GPIB::10", read_termination='\r')
 
 The default value depends on the bus system.  Generally, the sequence is empty,
-in particular for GPIB. For RS232 it's `\r`.
+in particular for GPIB. For RS232 it's ``\r``.
 
 You can specify the character to add to each outgoing message using the
-`write_termination` attribute.
+``write_termination`` attribute.
 
 
 `query_delay` and `send_end`
@@ -148,12 +148,12 @@ You can specify the character to add to each outgoing message using the
    single: send_end
 
 There are two further options related to message termination, namely
-`send_end` and `query_delay`.  `send_end` is a boolean.  If it's  `True` (the
+``send_end`` and ``query_delay``.  ``send_end`` is a boolean.  If it's  ``True`` (the
 default), the EOI line is asserted after each write operation,  signalling the
 end of the operation.  EOI is GPIB-specific but similar action  is taken for
 other interfaces.
 
-The argument `query_delay` is the time in seconds to wait after
+The argument ``query_delay`` is the time in seconds to wait after
 each write  operation.  So you could write::
 
    my_instrument = rm.open_resource("GPIB::10", send_end=False, delay=1.2)
diff --git a/docs/rvalues.rst b/docs/rvalues.rst
index 9d2ab61..383585c 100644
--- a/docs/rvalues.rst
+++ b/docs/rvalues.rst
@@ -11,24 +11,26 @@ have to transfer the function you want to generate.
 Basically, data like this can be transferred in two ways: in ASCII form (slow,
 but human readable) and binary (fast, but more difficult to debug).
 
-PyVISA Message Based Resources have two different methods for this called
-`query_ascii_values` and `query_binary_values`. It also has the convenient
-`query_values` which will use follow a previously established configuration.
+PyVISA Message Based Resources have two different methods for this
+called :meth:`pyvisa.resources.MessageBasedResource.query_ascii_values`
+and :meth:`pyvisa.resources.MessageBasedResource.query_binary_values`.
+It also has the convenient :meth:`pyvisa.resources.MessageBasedResource.query_values`
+which will use follow a previously established configuration.
 
 
 Reading ASCII values
 --------------------
 
-If your oscilloscope (open in the variable `inst`) has been configured to
-transfer data in **ASCII** when the `CURV?` command is issued, you can just
+If your oscilloscope (open in the variable ``inst``) has been configured to
+transfer data in **ASCII** when the ``CURV?`` command is issued, you can just
 query the values like this::
 
     >>> values = inst.query_ascii_values('CURV?')
 
-`values` will be `list` containing the values from the device.
+``values`` will be ``list`` containing the values from the device.
 
-In many cases you do not want a `list` but rather a different container type such
-as a `numpy.array`. You can of course cast the data afterwards like this::
+In many cases you do not want a ``list`` but rather a different container type such
+as a ``numpy.array``. You can of course cast the data afterwards like this::
 
     >>> values = np.array(inst.query_ascii_values('CURV?'))
 
@@ -37,25 +39,25 @@ you can just specify the container type in the query::
 
     >>> values = inst.query_ascii_values('CURV?', container=numpy.array)
 
-In `container` you can have any callable/type that takes an iterable.
+In ``container`` you can have any callable/type that takes an iterable.
 
 Some devices transfer data in ASCII but not as decimal numbers but rather hex
 or oct. Or you might want to receive an array of strings. In that case you can specify
-a `converter`. For example, if you expect to receive integers as hex:
+a ``converter``. For example, if you expect to receive integers as hex:
 
     >>> values = inst.query_ascii_values('CURV?', converter='x')
 
-`converter` can be one of the Python :ref:`string formatting codes <python:formatspec>`.
+``converter`` can be one of the Python :ref:`string formatting codes <python:formatspec>`.
 But you can also specify a callable that takes a single argument if needed.
-The default converter is `'f'`.
+The default converter is ``'f'``.
 
 Finally, some devices might return the values separated in an uncommon way. For example
-if the returned values are separated by a `'$'` you can do the following call:
+if the returned values are separated by a ``'$'`` you can do the following call:
 
     >>> values = inst.query_ascii_values('CURV?', separator='$')
 
 You can provide a function to takes a string and returns an iterable.
-Default value for the separator is `','` (comma)
+Default value for the separator is ``','`` (comma)
 
 .. _sec:reading-binary-data:
 
@@ -63,8 +65,8 @@ Default value for the separator is `','` (comma)
 Reading binary values
 ---------------------
 
-If your oscilloscope (open in the variable `inst`) has been configured to
-transfer data in **BINARY** when the `CURV?` command is issued, you need to
+If your oscilloscope (open in the variable ``inst``) has been configured to
+transfer data in **BINARY** when the ``CURV?`` command is issued, you need to
 know which type datatype (e.g. uint8, int8, single, double, etc) is being
 used. PyVISA use the same naming convention as the :ref:`struct module <python:format-characters>`.
 
@@ -80,7 +82,7 @@ Writing ASCII values
 --------------------
 
 To upload a function shape to arbitrary wave generator, the command might be
-`WLISt:WAVeform:DATA <waveform name>,<function data>` where `<waveform name>`
+``WLISt:WAVeform:DATA <waveform name>,<function data>`` where ``<waveform name>``
 tells the device under which name to store the data.
 
     >>> values = list(range(100))
@@ -90,29 +92,29 @@ Again, you can specify the converter code.
 
     >>> inst.write_ascii_values('WLISt:WAVeform:DATA somename,', values, converter='x')
 
-`converter` can be one of the Python :ref:`string formatting codes <python:formatspec>`.
+``converter`` can be one of the Python :ref:`string formatting codes <python:formatspec>`.
 But you can also specify a callable that takes a single argument if needed.
-The default converter is `'f'`.
+The default converter is ``'f'``.
 
-The separator can also be specified just like in `query_ascii_values`.
+The separator can also be specified just like in ``query_ascii_values``.
 
     >>> inst.write_ascii_values('WLISt:WAVeform:DATA somename,', values, converter='x', separator='$')
 
 You can provide a function to takes a iterable and returns an string.
-Default value for the separator is `','` (comma)
+Default value for the separator is ``','`` (comma)
 
 
 Writing binary values
 ---------------------
 
 To upload a function shape to arbitrary wave generator, the command might be
-`WLISt:WAVeform:DATA <waveform name>,<function data>` where `<waveform name>`
+``WLISt:WAVeform:DATA <waveform name>,<function data>`` where ``<waveform name>``
 tells the device under which name to store the data.
 
     >>> values = list(range(100))
     >>> inst.write_binary_values('WLISt:WAVeform:DATA somename,', values)
 
-Again you can specify the `datatype` and `endianness`.
+Again you can specify the ``datatype`` and ``endianness``.
 
     >>> inst.write_binary_values('WLISt:WAVeform:DATA somename,', values, datatype='d', is_big_endian=False)
 
@@ -124,8 +126,8 @@ Preconfiguring the transfer format
 Most of the cases, each device will transfer data in the same format every time.
 And making the call so detailed everytime can be annoying. For this purpose,
 PyVISA provides a way to preconfigure the default. Each Message Based
-Resources exposes an attribute named `values_format` which is an object with the following
-properties: `is_binary`, `datatype`, `is_big_endian`, `container`. For example to set
+Resources exposes an attribute named ``values_format`` which is an object with the following
+properties: ``is_binary``, ``datatype``, ``is_big_endian``, ``container``. For example to set
 e.g. little-endian doubles and a numpy array::
 
     >>> inst.values_format.is_binary = True
@@ -146,7 +148,7 @@ which will dispatch to the appropriate function and arguments.
 If you want to default to ASCII transfer, preconfiguring is a little bit more
 cumbersome as you need to specify the converters for both ways.
 
-For example with hex, with `'$'` as separator:
+For example with hex, with ``'$'`` as separator:
 
     >>> inst.values_format.is_binary = False
     >>> inst.values_format.converter = 'x'
diff --git a/docs/shell.rst b/docs/shell.rst
index 4dcb3d9..0943d90 100644
--- a/docs/shell.rst
+++ b/docs/shell.rst
@@ -14,7 +14,7 @@ that will show something the following prompt::
 
     (visa)
 
-At any time, you can type `?` or `help` to get a list of valid commands::
+At any time, you can type ``?`` or ``help`` to get a list of valid commands::
 
     (visa) help
 
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
index aaa92d8..d099d57 100644
--- a/docs/tutorial.rst
+++ b/docs/tutorial.rst
@@ -22,7 +22,7 @@ Let's go *in medias res* and have a look at a simple example::
 This example already shows the two main design goals of PyVISA: preferring
 simplicity over generality, and doing it the object-oriented way.
 
-After importing `visa`, we create a `ResourceManager` object. If called without
+After importing ``visa``, we create a ``ResourceManager`` object. If called without
 arguments, PyVISA will use the default backend (NI) which tries to find the
 VISA shared library for you. You can check, the location of the shared library
 used simply by:
@@ -31,34 +31,34 @@ used simply by:
     <ResourceManager('/path/to/visa.so')>
 
 .. note:: In some cases, PyVISA is not able to find the library for you
-          resulting in an `OSError`. To fix it, find the library path
+          resulting in an ``OSError``. To fix it, find the library path
           yourself and pass it to the ResourceManager constructor.
           You can also specify it in a configuration file as discussed
           in :ref:`configuring`.
 
 
-Once that you have a `ResourceManager`, you can list the available resources
-using the `list_resources` method. The output is a tuple listing the
+Once that you have a ``ResourceManager``, you can list the available resources
+using the ``list_resources`` method. The output is a tuple listing the
 :ref:`resource_names`.
 
 In this case, there is a GPIB instrument with instrument number 14, so you ask
-the `ResourceManager` to open "'GPIB0::14::INSTR'" and assign the returned
+the ``ResourceManager`` to open "'GPIB0::14::INSTR'" and assign the returned
 object to the *my_instrument*.
 
-Notice `open_resource` has given you an instance of `GPIBInstrument` class
-(a subclass of the more generic `Resource`).
+Notice ``open_resource`` has given you an instance of ``GPIBInstrument`` class
+(a subclass of the more generic ``Resource``).
 
     >>> print(my_instrument)
     <GPIBInstrument('GPIB::14')>
 
-There many `Resource` subclasses representing the different types of resources, but
-you do not have to worry as the `ResourceManager` will provide you with the appropiate
+There many ``Resource`` subclasses representing the different types of resources, but
+you do not have to worry as the ``ResourceManager`` will provide you with the appropiate
 class. You can check the methods and attributes of each class in the :ref:`api_resources`
 
-Then, you query the device with the following message: `'\*IDN?'`.
+Then, you query the device with the following message: ``'\*IDN?'``.
 Which is the standard GPIB message for "what are you?" or -- in some cases --
-"what's on your display at the moment?". `query` is a short form for a `write`
-operation to send a message, followed by a `read`.
+"what's on your display at the moment?". ``query`` is a short form for a ``write``
+operation to send a message, followed by a ``read``.
 
 So::
 
@@ -82,7 +82,7 @@ self-identification on the screen::
    print(itc4.read())
 
 Instead of separate write and read operations, you can do both with
-one `query()` call. Thus, the above source code is equivalent to::
+one ``query()`` call. Thus, the above source code is equivalent to::
 
    print(itc4.query("V"))