Tweak developer docs

conf.py

@@ -108,6 +108,7 @@ extlinks = {
     'bug': ('http://www.bay12games.com/dwarves/mantisbt/view.php?id=%s',
             'Bug '),
     'issue': ('https://github.com/DFHack/dfhack/issues/%s', 'Issue '),
+    'commit': ('https://github.com/DFHack/dfhack/commit/%s', 'Commit '),
 }
 
 # Add any paths that contain templates here, relative to this directory.

docs/Binpatches.rst

@@ -29,8 +29,7 @@ decent skill in `memory research <contributing-memory-research>`.
 
 * The patches are expected to be encoded in text format used by IDA.
 
-* See `this commit <https://github.com/DFHack/dfhack/commit/8a9e3d1a728>`_,
+* See :commit:`8a9e3d1a728` for examples.
-  when the 0.34.11 patches were discarded, for example patches.
 
 * :issue:`546` is about the future of the binpatches, and may be useful reading.
 
@@ -50,7 +49,7 @@ directly in memory at runtime::
     binpatch [check|apply|remove] <patchname>
 
 If the name of the patch has no extension or directory separators, the
-script uses ``hack/patches/<df-version>/<name>.dif``, thus auto-selecting
+script uses :file:`hack/patches/<df-version>/<name>.dif`, thus auto-selecting
 the version appropriate for the currently loaded executable.
 
 This is the preferred method; it's easier to debug, does not cause persistent

docs/Compile.rst

@@ -42,9 +42,11 @@ Contributing to DFHack
 If you want to get involved with the development, create an account on
 GitHub, make a clone there and then use that as your remote repository instead.
 
-We'd love that; join us on IRC (#dfhack channel on freenode) for discussion,
+We'd love that; join us on IRC_ (#dfhack channel on freenode) for discussion,
 and whenever you need help.
 
+.. _IRC: https://webchat.freenode.net/?channels=dfhack
+
 For lots more details on contributing to DFHack, including pull requests, code format,
 and more, please see `contributing-code`.
 
@@ -101,7 +103,7 @@ Before you can build anything, you'll also need ``cmake``. It is advisable to al
 You also need perl and the XML::LibXML and XML::LibXSLT perl packages (for the code generation parts).
 You should be able to find them in your distro repositories.
 
-To build Stonesense, you'll also need OpenGL headers.
+To build `stonesense`, you'll also need OpenGL headers.
 
 Here are some package install commands for various platforms:
 
@@ -109,15 +111,15 @@ Here are some package install commands for various platforms:
 
   * For the required Perl modules: ``perl-xml-libxml`` and ``perl-xml-libxslt`` (or through ``cpan``)
 
-* On 64-bit Ubuntu:
+* On 64-bit Ubuntu::
 
-  * ``apt-get install gcc cmake git gcc-multilib g++-multilib zlib1g-dev:i386 libxml-libxml-perl libxml-libxslt-perl``.
+    apt-get install gcc cmake git gcc-multilib g++-multilib zlib1g-dev:i386 libxml-libxml-perl libxml-libxslt-perl
 
-* On 32-bit Ubuntu:
+* On 32-bit Ubuntu::
 
-  * ``apt-get install gcc cmake git gcc-multilib g++-multilib zlib1g-dev libxml-libxml-perl libxml-libxslt-perl``.
+    apt-get install gcc cmake git gcc-multilib g++-multilib zlib1g-dev libxml-libxml-perl libxml-libxslt-perl
 
-* Debian-derived distros should have similar requirements.
+* Debian and derived distros should have similar requirements to Ubuntu.
 
 
 Build
@@ -505,9 +507,8 @@ or ``RelWithDebInfo``.
 Then build the ``INSTALL`` target listed under ``CMakePredefinedTargets``.
 
 
-##########################
 Building the documentation
-##########################
+==========================
 
 DFHack documentation, like the file you are reading now, is created as .rst files,
 which are in `reStructuredText (reST) <http://sphinx-doc.org/rest.html>`_ format.
@@ -530,7 +531,7 @@ The main thing you lose in plain text format is hyperlinking.)
 
 
 Enabling documentation building
-===============================
+-------------------------------
 First, make sure you have followed all the necessary steps for your platform as
 outlined in the rest of this document.
 
@@ -550,7 +551,7 @@ through the GUI, or else if you want to use an alternate file, such as
 Or you could just run ``cmake`` on the command line like in other platforms.
 
 Required dependencies
-=====================
+---------------------
 In order to build the documentation, you must have Python with Sphinx
 version 1.3.1 or later. Both Python 2.x and 3.x are supported.
 

docs/Contributing.rst

@@ -69,6 +69,7 @@ on how to write one yet, but it should be easy enough to copy one and just follo
 
 Other than through plugins, it is possible to use DFHack via remote access interface,
 or by writing scripts in Lua or Ruby.  There are plenty of examples in the scripts folder.
+The `lua-api` is quite well documented.
 
 The most important parts of DFHack are the Core, Console, Modules and Plugins.
 
@@ -85,7 +86,9 @@ The most important parts of DFHack are the Core, Console, Modules and Plugins.
 
 Rudimentary API documentation can be built using doxygen (see build options
 in ``CMakeCache.txt`` or with ``ccmake`` or ``cmake-gui``).  The full DFHack
-documentation is built with Sphinx, which runs automatically at compile time.
+documentation is built with Sphinx_, which runs automatically at compile time.
+
+.. _Sphinx: http://www.sphinx-doc.org
 
 DFHack consists of variously licensed code, but invariably weak copyleft.
 The main license is zlib/libpng, some bits are MIT licensed, and some are
@@ -101,14 +104,14 @@ in the ``library/xml/`` submodule.
 
 See https://github.com/DFHack/df-structures, and the documentation linked in the index.
 
-Data structure layouts are described in files following the ``df.\*.xml`` name pattern.
+Data structure layouts are described in files following the ``df.*.xml`` name pattern.
 This information is transformed by a perl script into C++ headers describing the
 structures, and associated metadata for the Lua wrapper. These headers and data
 are then compiled into the DFHack libraries, thus necessitating a compatibility
 break every time layouts change; in return it significantly boosts the efficiency
 and capabilities of DFHack code.
 
-Global object addresses are stored in ``symbols.xml``, which is copied to the dfhack
+Global object addresses are stored in :file:`symbols.xml`, which is copied to the dfhack
 release package and loaded as data at runtime.
 
 Remote access interface
@@ -118,13 +121,13 @@ socket. Both the core and plugins can define remotely accessible methods. The
 ``dfhack-run`` command uses this interface to invoke ordinary console commands.
 
 Currently the supported set of requests is limited, because the developers don't
-know what exactly is most useful.  ``remotefortressreader`` provides a fairly
+know what exactly is most useful.  `remotefortressreader` provides a fairly
-comprehensive interface for visualisers such as Armok Vision.
+comprehensive interface for visualisers such as :forums:`Armok Vision <146473>`.
 
 
 Documentation Standards
 =======================
-DFHack documentation is built with Sphinx, and configured automatically
+DFHack documentation is built with Sphinx_, and configured automatically
 through CMake.  If you want to build the docs *only*, use this command::
 
     sphinx-build . docs/html
@@ -134,10 +137,10 @@ there are a few important standards for completeness and consistent style.  Trea
 this section as a guide rather than iron law, match the surrounding text, and you'll
 be fine.
 
-Everything should be documented!  For plugins, it's a work in progress - use
+Everything should be documented!  If it's not clear *where* a particular
-``docs/Plugins.rst`` for now.  Core functions and general explanations should
+thing should be documented, ask on IRC or in the DFHack thread on Bay12 -
-go in the documents for that component; if it's not clear add a new section
+as well as getting help, you'll be providing valuable feedback that
-as some may be missing.
+makes it easier for future readers!
 
 Scripts can use a custom autodoc function, based on the Sphinx ``include``
 directive and Ruby docstring conventions - any lines between ``=begin`` and

docs/Lua API.rst

@@ -1,3 +1,5 @@
+.. _lua-api:
+
 ##############
 DFHack Lua API
 ##############