Improve documentation

Author: sethrj

.gitignore

@@ -1,3 +1,4 @@
+/build/
 # Prerequisites
 *.d
 

CMakeLists.txt

@@ -12,7 +12,7 @@ project(Flibcpp VERSION 0.1.0 LANGUAGES CXX Fortran)
 # SWIG setup
 #---------------------------------------------------------------------------#
 
-option(USE_SWIG "Enable SWIG generation" ON)
+option(USE_SWIG "Enable SWIG generation" OFF)
 if (USE_SWIG)
   find_package(SWIG)
 endif()

README.md

@@ -29,8 +29,9 @@ recent version of CMake:
    3.8 or higher)
 3. Install using `make install`
 
-More detailed installation instructions will be {are?} available in the
-documentation.  An example Fortran application that depends only on Flibcpp is
+More detailed installation instructions are available [in the
+documentation](https://flibcpp.readthedocs.io/en/latest/introduction.html#installation).
+An example Fortran application that depends only on Flibcpp is
 available [on Github](https://github.com/swig-fortran/flibcpp-example-app).
 
 ## Documentation

doc/introduction.rst

@@ -9,6 +9,57 @@ Introduction
 The purpose of this library is to provide access to efficient and robust
 algorithms and data types commonly used in scientific applications.
 
+Installation
+============
+
+Flibcpp is built using modern CMake_, and it has no external dependencies. This
+makes installation quite simple as long as you have a relatively recent
+software stack with a Fortran and compatible C++ compiler.
+
+1. Download and install CMake if it's not already on your system. It is highly
+   recommended to use a package manager such as Homebrew_ for Mac or YUM_ for
+   Red Hat Linux.
+2. Download the `Flibcpp source code`_ from GitHub if you haven't already.
+3. Create a new build directory (for example purposes, create a subdirectory
+   named ``build`` inside your downloaded source directory) and ``cd`` to it.
+4. Run CMake: ``cmake ..``
+5. Make and install (by default it will install to ``/usr/local``):
+   ``make install``.
+
+.. _CMake: https://cmake.org
+.. _Homebrew: https://brew.sh
+.. _YUM: https://access.redhat.com/solutions/9934
+.. _Flibcpp source code: https://github.com/swig-fortran/flibcpp/releases .
+
+Downstream usage
+================
+
+The Flibcpp library is most easily used when your downstream app is built with
+CMake. It should require a single line to initialize::
+
+   find_package(Flibcpp REQUIRED CONFIG)
+
+and a single line to link against your app or library::
+
+   target_link_libraries(example_backend Flibcpp::flc_random Flibcpp::flc_algorithm)
+
+If your installation prefix for Flibcpp is a system default path (such as
+``/usr/local``) or in your ``$CMAKE_PREFIX_PATH`` environment variable, it
+should automatically find the necessary CMake configure file.
+
+An `example Fortran application`_ that depends only on Flibcpp is
+available on Github.
+
+.. _example Fortran application: https://github.com/swig-fortran/flibcpp-example-app).
+
+----
+
+If you're using a simple standalone Makefile to build your Fortran code, you
+will have to inform the compiler of the proper include path, library path, and
+library names. Depending on your system configuration, you might have to
+also explicitly link your app against the compiler's C++ standard libraries
+using ``-lstdc++``.
+
 .. ############################################################################
 .. end of doc/introduction.rst
 .. ############################################################################

doc/modules/algorithm.rst

@@ -111,6 +111,7 @@ the first index will be the point at which the element would be located if it
 were present.
 
 Example::
+
   use flc_algorithm, only : equal_range, INDEX_INT
   implicit none
   integer(INDEX_INT) :: first, last