#!/bin/sh
#
# Create sphinx api docs.

# lazily slapped together, will come back to improve
rm -rf build
sphinx-apidoc -f -o . ../hypatia
sphinx-build . build
firefox build/index.html

#!/bin/sh
#
# Create API documentation using Sphinx:
#
#     http://sphinx-doc.org/
#
# If the $BROWSER environment variable is set then the script will use
# that to open the documentation locally.  If the variable does not
# exist then the script falls back to using Firefox.
#
######################################################################

BROWSER="${BROWSER:=firefox}"

# Delete existing documentation.  First, however, we change to the
# `docs/` directory.  Ninety-nine percent of the time we will already
# be in that directory when running this script.  But there are two
# `build/` directories: on at the top level and one as a sub-directory
# of `docs/`, thus we change directories to be sure we delete the
# correct `build/` directory.

cd "$(git rev-parse --show-toplevel)/docs"

if [ -d "./build" ]; then
    rm ./build -rf
fi

# Build the documentation.

sphinx-apidoc -f -o . ../hypatia
sphinx-build . build

# Open locally if the build worked.  We give a full `file://` URI to
# our browser because some browsers will incorrectly interpret it as a
# URL such as `http://build/index.html`, which can also happen (less
# likely) depending on local DNS settings.  Using a `file://` URI
# avoids both of these problems.

if [ -e "./build/index.html" ]; then
    "$BROWSER" "file://$(git rev-parse --show-toplevel)/build/index.html"
fi

Improve the script to generate documentation using Sphinx
[Feature] Improve the script to generate documentation using Sphinx

This patch implements the following improvements to the shell script
`docs/make-sphinx.sh`, which builds our documentation:

1. The comment header links to the Sphinx site just in case developers
   do not have Sphinx installed.

2. The script looks for the `$BROWSER` environment variable.  If it
   exists then the script treats that as the name of the browser to
   use for opening the documentation locally.  If the variable is not
   set then the script falls back to using `firefox` like before.

3. Before deleting the existing documentation the script will `cd`
   into the `docs/` directory.  Even though we will almost always be
   in that directory in the first place, this prevents us from
   accidentally deleting the `build/` directory at the top level of
   the project.

4. The script will not attempt to delete `build/` if it does not exist
   so that `rm` will not stop the script with an error.

5. Instead of opening `build/index.html` with the browser the script
   now uses a full-path `file://` URI to the file, e.g.

    file:///home/eric/Projects/Hypatia/Engine/docs/build/index.html

   This handles a problem in which some browsers will interpter a
   simple `build/index.html` on the command-line to be a web address,
   e.g. `http://build/index.html`.

6. Finally, the script will only open the documentation locally if the
   build was successful and `build/index.html` exists.

Signed-off-by: Eric James Michael Ritz <3d928645612786af07f011fdfbce45f81efe5a40@plutono.com>
Tested-by: Alice Jenkinson <1fe13ea0b10cb8ffcb6e53f6309ad98b4c50c8e3@gmail.com>
