Documentation improvements

CHANGES.rst

@@ -32,7 +32,7 @@ Incompatible changes
 Bug fixes and minor changes
 ---------------------------
 
-+ `#141`_, `#142`_: Review documentation.
++ `#141`_, `#142`_, `#150`_: Review documentation.
 
 + `#145`_: Review build tool chain.
 
@@ -45,6 +45,7 @@ Bug fixes and minor changes
 .. _#147: https://github.com/icatproject/python-icat/pull/147
 .. _#148: https://github.com/icatproject/python-icat/issues/148
 .. _#149: https://github.com/icatproject/python-icat/pull/149
+.. _#150: https://github.com/icatproject/python-icat/pull/150
 
 
 .. _changes-1_2_0:

doc/src/conf.py

@@ -68,8 +68,12 @@ def make_meta_rst(last_release):
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
-    'sphinx_copybutton',
 ]
+try:
+    import sphinx_copybutton
+    extensions.append('sphinx_copybutton')
+except ImportError:
+    pass
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -80,6 +84,17 @@ def make_meta_rst(last_release):
 # The master toctree document.
 master_doc = 'index'
 
+# Enable automatic numbering of figures, tables and code-blocks
+numfig = True
+
+# Strings to format figure, table, code-block, and section numbers
+numfig_format = {
+    'figure': "Figure %s",
+    'table': "Table %s",
+    'code-block': "Snippet %s",
+    'section': "Section %s",
+}
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -102,7 +117,10 @@ def make_meta_rst(last_release):
 
 # -- Options for intersphinx extension ---------------------------------------
 
-intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'lxml': ('https://lxml.de/apidoc/', None),
+}
 
 # -- Options for HTML output -------------------------------------------------
 

doc/src/config.rst

@@ -171,9 +171,9 @@ A few derived variables are also set in
     | `promptPass`    | ``-P``, ``--prompt-pass``   |                       | :const:`False` | no        | \(3),(4),(5) |
     +-----------------+-----------------------------+-----------------------+----------------+-----------+--------------+
 
-See the table for an overview of predefined configuration variables.
-Mandatory means that an error will be raised in
-:meth:`icat.config.Config.getconfig` if no value is found for the
+See :numref:`tab-config-vars` for an overview of predefined
+configuration variables.  Mandatory means that an error will be raised
+in :meth:`icat.config.Config.getconfig` if no value is found for the
 configuration variable in question.
 
 Notes: