Documentation.rst: move dependencies up to top-level section + misc tweaks

Makes it easier to jump to "Building the documentation"

docs/Documentation.rst

@@ -119,15 +119,13 @@ Add link targets if you need them, but otherwise plain headings are preferred.
 Scripts have link targets created automatically.
 
 
-Building the documentation
+Required dependencies
-==========================
+=====================
 
 .. highlight:: shell
 
-Required dependencies
----------------------
 In order to build the documentation, you must have Python with Sphinx
-version |sphinx_min_version| or later. Both Python 2.x and 3.x are supported.
+version |sphinx_min_version| or later. Python 3 is recommended.
 
 When installing Sphinx from OS package managers, be aware that there is
 another program called Sphinx, completely unrelated to documentation management.
@@ -146,7 +144,7 @@ For more detailed platform-specific instructions, see the sections below:
 
 
 Linux
-~~~~~
+-----
 Most Linux distributions will include Python by default. If not, start by
 installing Python (preferably Python 3). On Debian-based distros::
 
@@ -172,7 +170,7 @@ system-wide by running pip with ``sudo``. In any case, you will need the folder
 containing ``sphinx-build`` to be in your ``$PATH``.
 
 macOS
-~~~~~
+-----
 macOS has Python 2.7 installed by default, but it does not have the pip package manager.
 
 You can install Homebrew's Python 3, which includes pip, and then install the
@@ -193,7 +191,7 @@ If not, just installing sphinx-doc for macOS's system Python 2.7 is fine.
 
 
 Windows
-~~~~~~~
+-------
 Python for Windows can be downloaded `from python.org <https://www.python.org/downloads/>`_.
 The latest version of Python 3 is recommended, as it includes pip already.
 
@@ -210,6 +208,11 @@ Once you have pip available, you can install Sphinx with the following command::
 Note that this may require opening a new (admin) command prompt if you just
 installed pip from the same command prompt.
 
+Building the documentation
+==========================
+
+Once the required dependencies are installed, there are multiple ways to run
+Sphinx to build the docs:
 
 Using CMake
 -----------
@@ -230,7 +233,7 @@ ways to do this:
 
 * You can edit the ``BUILD_DOCS`` setting in CMakeCache.txt directly
 
-* You can use the CMake GUI to change ``BUILD_DOCS``
+* You can use the CMake GUI or ``ccmake`` to change the ``BUILD_DOCS`` setting
 
 * On Windows, if you prefer to use the batch scripts, you can run
   ``generate-msvc-gui.bat`` and set ``BUILD_DOCS`` through the GUI. If you are
@@ -238,19 +241,28 @@ ways to do this:
   it to add the flag. You can also run ``cmake`` on the command line, similar to
   other platforms.
 
+The generated documentation will be stored in ``docs/html`` in the root DFHack
+folder, and will be installed to ``hack/docs`` when you next install DFHack in a
+DF folder.
+
 Running Sphinx manually
 -----------------------
 
-You can also build the documentation without going through CMake, which may be
+You can also build the documentation without running CMake - this is faster if
-faster. There is a ``docs/build.sh`` script provided for Linux and macOS that
+you only want to rebuild the documentation regardless of any code changes. There
-will run essentially the same command that CMake runs - see the script for
+is a ``docs/build.sh`` script provided for Linux and macOS that will run
-additional options.
+essentially the same command that CMake runs when building the docs - see the
+script for additional options.
 
 To build the documentation with default options, run the following command from
 the root DFHack folder::
 
     sphinx-build . docs/html
 
+The resulting documentation will be stored in ``docs/html`` (you can specify
+a different path when running ``sphinx-build`` manually, but be warned that
+Sphinx may overwrite existing files in this folder).
+
 Sphinx has many options to enable clean builds, parallel builds, logging, and
 more - run ``sphinx-build --help`` for details.
 
@@ -263,7 +275,7 @@ want to build a PDF version locally, you will need ``pdflatex``, which is part
 of a TeX distribution. The following command will then build a PDF, located in
 ``docs/pdf/latex/DFHack.pdf``, with default options::
 
-  sphinx-build -M latexpdf . ./docs/pdf
+  sphinx-build -M latexpdf . docs/pdf
 
 There is a ``docs/build-pdf.sh`` script provided for Linux and macOS that runs
 this command for convenience - see the script for additional options.
@@ -272,10 +284,11 @@ this command for convenience - see the script for additional options.
 
 Building the changelogs
 =======================
-If you have Python installed, but do not want to build all of the documentation,
+If you have Python installed, you can build just the changelogs without building
-you can build the changelogs with the ``docs/gen_changelog.py`` script. This
+the rest of the documentation by running the ``docs/gen_changelog.py`` script.
-script provides additional options, including one to build individual changelogs
+This script provides additional options, including one to build individual
-for all DFHack versions - run ``python docs/gen_changelog.py --help`` for details.
+changelogs for all DFHack versions - run ``python docs/gen_changelog.py --help``
+for details.
 
 Changelog entries are obtained from ``changelog.txt`` files in multiple repos.
 This allows changes to be listed in the same repo where they were made. These