Docs: Nixify (kadena-io#584)

* [docs] Use Nix to fix Python versions [skip ci]

* [docs] Update README [skip ci]

* [docs] Regenerate `.rst` files [skip ci]

docs/README.md

@@ -1,50 +1,44 @@
-# DEVELOPER IMPORTANT NOTE
+# Documentation Guideline
 
-The docs system for Pact involves a lot of generated files that are then picked up from Github by
-`readthedocs.org`. The implications of this are:
+Rendered Documentation: https://pact-language.readthedocs.io/en/stable/
 
-- **Most `.rst` files are autogenerated,** at least in the `en` folder. Manual edits to `.rst` files in `en` are usually in the wrong place:
+**Contents**
 
-  - For natives, you need to change the Haskell code that produces the function docs in `Pact.Native` and elsewhere.
+1. Developer Warning
+2. Setup
+3. File Layout
+4. Documentation Workflow
+5. Localization
 
-  - For everything else, chances are you should be editing a `.md` file such as `pact-reference.md`.
+## Developers: Please Read
 
-- **Readthedocs.org auto-builds on updates to master**. Thus any changes to `.rst` files should generally only accompany
-a release. Changes to `.md` files are part of normal dev during a release cycle however.
+We use ReadTheDocs for our documentation, which is generated from `.rst` files
+found in the `docs/` directory. The implications of this are:
 
-# Documentation Guideline
+- **Most `.rst` files are autogenerated,** at least in the `en` folder. Manually
+  editing these `.rst` files is almost always a mistake.
 
-[Read the Docs](https://readthedocs.org/) uses the `.rst` files found in `docs/` to generate Pact's
-documentation website.
-Pact's current Read the Docs website can be found [here](http://pact-language.readthedocs.io/en/latest/pact-reference.html).
+  - For native functions, you need to change the Haskell code that produces the
+    function docs in `Pact.Native` and elsewhere.
+  - For everything else, chances are you should be editing a `.md` file such as
+    `pact-reference.md`.
 
-**Contents**
+- Our ReadTheDocs configuration produces two versions of our docs: `stable` and
+  `master`.
 
-1. Setup
-2. File Layout
-3. Documentation Workflow
-4. Localization
+  - `stable` is the default for https://pact-language.readthedocs.io/, and only
+    updates upon the creation of a new Github release.
+  - `latest` updates upon every merge to our Github `master` branch.
 
 ## Setup
 
-To generate Pact's documentation, first download the following packages using your favorite package manager:
-
-* [Sphinx](http://www.sphinx-doc.org/en/master/)
-* [Pandoc](https://pandoc.org/installing.html)
-
-For OSX users with Python installed, download Sphinx via:
+We use Python, Sphinx, and Pandoc to generate the official docs. To ensure that
+everyone is using the same software versions (thereby rendering the docs in the
+same way), our scripts use [Nix](https://nixos.org/nix/).
 
-```
-$ pip install sphinx sphinx-autobuild
-```
-
-And install Pandoc via:
-
-```
-$ brew install pandoc
-```
+With Nix installed, make sure your Channels are up to date with `nix-channel --update`.
 
-More Read the Docs setup instructions can be found [here](http://docs.readthedocs.io/en/latest/getting_started.html).
+Now you're ready to generate Pact's documentation.
 
 ## File Layout
 
@@ -137,7 +131,7 @@ $ ln -s ../img img
 5. Copy `docs/jp/index.rst` to your subdirectory. Within it, change the title line
    to the translation of "Pact Language Reference".
 
-6. Add the following to `docs/build.sh`, matching the other translations:
+6. Add the following to `docs/work.sh`, matching the other translations:
 
 ```bash
 # --- Croatian Docs --- #

docs/build.sh

@@ -1,38 +1,4 @@
 #!/bin/bash
 
-# pip install sphinx sphinx-autobuild sphinx_rtd_theme
-
-# --- English Docs --- #
-cd en/
-rm -rf _build
-
-pandoc -s -t rst pact-reference.md -o pact-reference.rst
-pandoc -s -t rst pact-functions.md -o pact-functions.rst
-pandoc -s -t rst pact-properties.md -o pact-properties.rst
-pandoc -s -t rst pact-properties-api.md -o pact-properties-api.rst
-
-# escape +, - headings
-perl -p0777i -e 's/^(\+|\-)\n~/\\\1\n~~/gm' pact-reference.rst
-perl -p0777i -e 's/^(\+|\-)\n~/\\\1\n~~/gm' pact-functions.rst
-perl -p0777i -e 's/^(\+|\-)\n~/\\\1\n~~/gm' pact-properties-api.rst
-
-sphinx-build -b html -d _build/doctrees . _build/html
-
-# --- Japanese Docs --- #
-cd ..
-cd ja/
-rm -rf _build
-
-pandoc -s -t rst pact-reference.md -o pact-reference.rst
-perl -p0777i -e 's/^(\+|\-)\n~/\\\1\n~~/gm' pact-reference.rst
-sphinx-build -b html -d _build/doctrees . _build/html
-
-
-# --- Korean Docs --- #
-cd ..
-cd ko/
-rm -rf _build
-
-pandoc -s -t rst pact-reference.md -o pact-reference.rst
-perl -p0777i -e 's/^(\+|\-)\n~/\\\1\n~~/gm' pact-reference.rst
-sphinx-build -b html -d _build/doctrees . _build/html
+# --- Jump into Nix Shell --- #
+nix-shell --pure -p python3 python37Packages.sphinx python37Packages.sphinx_rtd_theme pandoc perl --run "./work.sh"