diff --git a/.gitignore b/.gitignore
index 0374201a3b75d503a19ea078170cb14f0653b6b9..cfd3c4e63b6dd1189d22618cf494b5ce38650081 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,9 +15,9 @@ dist-*
 register.sh
 ./cabal.config
 cabal-tests.log
+.python-sphinx-virtualenv/
 
 /Cabal/dist/
-/Cabal/.python-sphinx-virtualenv/
 /Cabal/tests/Setup
 /Cabal/Setup
 /Cabal/source-file-list
diff --git a/.readthedocs.yml b/.readthedocs.yml
index 2660528b8316828f549012fb3bba823a50db5498..347901d93bdfeafa94d23a8e3143f9df4e6be605 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,9 +1,9 @@
 version: 2
 
 sphinx:
-  configuration: Cabal/doc/conf.py
+  configuration: doc/conf.py
 
 python:
   version: 3.7
   install:
-    - requirements: Cabal/doc/requirements.txt
+    - requirements: doc/requirements.txt
diff --git a/Cabal/Makefile b/Cabal/Makefile
index 88b50672f554a62720af940e475eb3919c07dfb1..12197fe2e7a4c27b5437d04537b24f33685abfb8 100644
--- a/Cabal/Makefile
+++ b/Cabal/Makefile
@@ -20,14 +20,10 @@ SOURCES=Distribution/*.hs Distribution/Simple/*.hs \
 CONFIG_STAMP=dist/setup-config
 BUILD_STAMP=dist/build/libHSCabal-$(VERSION).a
 HADDOCK_STAMP=dist/doc/html/Cabal/index.html
-USERGUIDE_STAMP=dist/doc/users-guide/index.html
 SDIST_STAMP=dist/Cabal-$(VERSION).tar.gz
 DISTLOC=dist/release
 DIST_STAMP=$(DISTLOC)/Cabal-$(VERSION).tar.gz
 
-# TODO: when we have sphinx-build2 ?
-SPHINXCMD:=sphinx-build
-
 COMMA=,
 
 setup: $(SOURCES) Setup.hs
@@ -51,20 +47,6 @@ haddock: $(HADDOCK_STAMP)
 $(HADDOCK_STAMP) : $(CONFIG_STAMP) $(BUILD_STAMP)
 	./setup haddock
 
-SPHINX_HTML_OUTDIR=dist/doc/users-guide
-
-# do pip install everytime so we have up to date requirements when we build
-users-guide: .python-sphinx-virtualenv $(USERGUIDE_STAMP)
-$(USERGUIDE_STAMP) : doc/*.rst
-	mkdir -p $(SPHINX_HTML_OUTDIR)
-	(. ./.python-sphinx-virtualenv/bin/activate && pip install -r doc/requirements.txt && $(SPHINXCMD) doc $(SPHINX_HTML_OUTDIR))
-
-docs: haddock users-guide
-
-.python-sphinx-virtualenv:
-	python3 -m venv .python-sphinx-virtualenv
-	(. ./.python-sphinx-virtualenv/bin/activate)
-
 clean:
 	rm -rf dist/
 	rm -f setup
@@ -93,17 +75,15 @@ $(SDIST_STAMP) : $(BUILD_STAMP)
 	./setup sdist
 
 dist: $(DIST_STAMP)
-$(DIST_STAMP) : $(HADDOCK_STAMP) $(USERGUIDE_STAMP) $(SDIST_STAMP)
+$(DIST_STAMP) : $(HADDOCK_STAMP) $(SDIST_STAMP)
 	rm -rf $(DISTLOC)
 	mkdir $(DISTLOC)
 	tar -xzf $(SDIST_STAMP) -C $(DISTLOC)/
 	mkdir -p $(DISTLOC)/Cabal-$(VERSION)/doc
 	cp -r dist/doc/html $(DISTLOC)/Cabal-$(VERSION)/doc/API
-	cp -r dist/doc/users-guide $(DISTLOC)/Cabal-$(VERSION)/doc/
 	cp ChangeLog.md $(DISTLOC)/Cabal-$(VERSION)/
 	tar --format=ustar -C $(DISTLOC) -czf $(DISTLOC)/Cabal-$(VERSION).tar.gz Cabal-$(VERSION)
 	mkdir $(DISTLOC)/doc
-	mv $(DISTLOC)/Cabal-$(VERSION)/doc/users-guide $(DISTLOC)/doc
 	mv $(DISTLOC)/Cabal-$(VERSION)/doc/API $(DISTLOC)/doc
 	mv $(DISTLOC)/Cabal-$(VERSION)/ChangeLog.md $(DISTLOC)/
 	rm -r $(DISTLOC)/Cabal-$(VERSION)/
diff --git a/Makefile b/Makefile
index e8ab181faf4f5151aa8456af5d3bbe6d396803b6..030d5c65812d176a2a9d2f475b99d23add3ff821 100644
--- a/Makefile
+++ b/Makefile
@@ -58,7 +58,7 @@ $(TEMPLATE_MACROS) : boot/cabal_macros.template.h cabal-dev-scripts/src/GenCabal
 
 # generated docs
 
-Cabal/doc/buildinfo-fields-reference.rst : phony
+doc/buildinfo-fields-reference.rst : phony
 	cabal build --builddir=dist-newstyle-bi --project-file=cabal.project.buildinfo buildinfo-reference-generator
 	$$(cabal-plan list-bin --builddir=dist-newstyle-bi buildinfo-reference-generator) buildinfo-reference-generator/template.zinza | tee $@
 
@@ -226,3 +226,25 @@ weeder :
 .PHONY : tags
 tags :
 	hasktags -b Cabal/Distribution Cabal/Cabal-described/src Cabal/Language cabal-install/Distribution cabal-testsuite/src
+
+# documentation
+##############################################################################
+
+# TODO: when we have sphinx-build2 ?
+SPHINXCMD:=sphinx-build
+SPHINX_HTML_OUTDIR:=dist-newstyle/doc/users-guide
+USERGUIDE_STAMP:=$(SPHINX_HTML_OUTDIR)/index.html
+
+# do pip install everytime so we have up to date requirements when we build
+users-guide: .python-sphinx-virtualenv $(USERGUIDE_STAMP)
+$(USERGUIDE_STAMP) : doc/*.rst
+	mkdir -p $(SPHINX_HTML_OUTDIR)
+	(. ./.python-sphinx-virtualenv/bin/activate && pip install -r doc/requirements.txt && $(SPHINXCMD) doc $(SPHINX_HTML_OUTDIR))
+
+docs: haddock users-guide
+
+.python-sphinx-virtualenv:
+	python3 -m venv .python-sphinx-virtualenv
+	(. ./.python-sphinx-virtualenv/bin/activate)
+
+
diff --git a/Cabal/doc/README.md b/doc/README.md
similarity index 100%
rename from Cabal/doc/README.md
rename to doc/README.md
diff --git a/Cabal/doc/_templates/layout.html b/doc/_templates/layout.html
similarity index 100%
rename from Cabal/doc/_templates/layout.html
rename to doc/_templates/layout.html
diff --git a/Cabal/doc/bugs-and-stability.rst b/doc/bugs-and-stability.rst
similarity index 100%
rename from Cabal/doc/bugs-and-stability.rst
rename to doc/bugs-and-stability.rst
diff --git a/Cabal/doc/buildinfo-fields-reference.rst b/doc/buildinfo-fields-reference.rst
similarity index 100%
rename from Cabal/doc/buildinfo-fields-reference.rst
rename to doc/buildinfo-fields-reference.rst
diff --git a/Cabal/doc/cabal-commands.rst b/doc/cabal-commands.rst
similarity index 100%
rename from Cabal/doc/cabal-commands.rst
rename to doc/cabal-commands.rst
diff --git a/Cabal/doc/cabal-package.rst b/doc/cabal-package.rst
similarity index 100%
rename from Cabal/doc/cabal-package.rst
rename to doc/cabal-package.rst
diff --git a/Cabal/doc/cabal-project.rst b/doc/cabal-project.rst
similarity index 100%
rename from Cabal/doc/cabal-project.rst
rename to doc/cabal-project.rst
diff --git a/Cabal/doc/cabaldomain.py b/doc/cabaldomain.py
similarity index 100%
rename from Cabal/doc/cabaldomain.py
rename to doc/cabaldomain.py
diff --git a/Cabal/doc/concepts-and-development.rst b/doc/concepts-and-development.rst
similarity index 100%
rename from Cabal/doc/concepts-and-development.rst
rename to doc/concepts-and-development.rst
diff --git a/Cabal/doc/conf.py b/doc/conf.py
similarity index 99%
rename from Cabal/doc/conf.py
rename to doc/conf.py
index 8bc4acd3d616e4030db1382fafb52a82ff66e5bf..a8830728ff5015f66d9087b73121512e53930f26 100644
--- a/Cabal/doc/conf.py
+++ b/doc/conf.py
@@ -68,13 +68,13 @@ html_static_path = ['images']
 html_use_smartypants = True
 html_show_copyright = True
 html_context = {
-    'source_url_prefix': "https://github.com/haskell/cabal/tree/master/Cabal/doc/",
+    'source_url_prefix': "https://github.com/haskell/cabal/tree/master/doc/",
     "display_github": True,
     "github_host": "github.com",
     "github_user": "haskell",
     "github_repo": 'cabal',
     "github_version": "master/",
-    "conf_py_path": "Cabal/doc/",
+    "conf_py_path": "doc/",
     "source_suffix": '.rst',
 }
 
diff --git a/Cabal/doc/config-and-install.rst b/doc/config-and-install.rst
similarity index 100%
rename from Cabal/doc/config-and-install.rst
rename to doc/config-and-install.rst
diff --git a/Cabal/doc/developing-packages.rst b/doc/developing-packages.rst
similarity index 100%
rename from Cabal/doc/developing-packages.rst
rename to doc/developing-packages.rst
diff --git a/Cabal/doc/file-format-changelog.rst b/doc/file-format-changelog.rst
similarity index 100%
rename from Cabal/doc/file-format-changelog.rst
rename to doc/file-format-changelog.rst
diff --git a/Cabal/doc/getting-started.rst b/doc/getting-started.rst
similarity index 100%
rename from Cabal/doc/getting-started.rst
rename to doc/getting-started.rst
diff --git a/Cabal/doc/hcar/.gitignore b/doc/hcar/.gitignore
similarity index 100%
rename from Cabal/doc/hcar/.gitignore
rename to doc/hcar/.gitignore
diff --git a/Cabal/doc/hcar/Cabal-201604.tex b/doc/hcar/Cabal-201604.tex
similarity index 100%
rename from Cabal/doc/hcar/Cabal-201604.tex
rename to doc/hcar/Cabal-201604.tex
diff --git a/Cabal/doc/hcar/Cabal-201611.tex b/doc/hcar/Cabal-201611.tex
similarity index 100%
rename from Cabal/doc/hcar/Cabal-201611.tex
rename to doc/hcar/Cabal-201611.tex
diff --git a/Cabal/doc/hcar/Cabal-201811.tex b/doc/hcar/Cabal-201811.tex
similarity index 100%
rename from Cabal/doc/hcar/Cabal-201811.tex
rename to doc/hcar/Cabal-201811.tex
diff --git a/Cabal/doc/hcar/hcar.sty b/doc/hcar/hcar.sty
similarity index 100%
rename from Cabal/doc/hcar/hcar.sty
rename to doc/hcar/hcar.sty
diff --git a/Cabal/doc/hcar/main.tex b/doc/hcar/main.tex
similarity index 100%
rename from Cabal/doc/hcar/main.tex
rename to doc/hcar/main.tex
diff --git a/Cabal/doc/images/Cabal-dark.png b/doc/images/Cabal-dark.png
similarity index 100%
rename from Cabal/doc/images/Cabal-dark.png
rename to doc/images/Cabal-dark.png
diff --git a/Cabal/doc/index.rst b/doc/index.rst
similarity index 100%
rename from Cabal/doc/index.rst
rename to doc/index.rst
diff --git a/Cabal/doc/installing-packages.rst b/doc/installing-packages.rst
similarity index 100%
rename from Cabal/doc/installing-packages.rst
rename to doc/installing-packages.rst
diff --git a/Cabal/doc/intro.rst b/doc/intro.rst
similarity index 100%
rename from Cabal/doc/intro.rst
rename to doc/intro.rst
diff --git a/Cabal/doc/misc.rst b/doc/misc.rst
similarity index 100%
rename from Cabal/doc/misc.rst
rename to doc/misc.rst
diff --git a/Cabal/doc/nix-integration.rst b/doc/nix-integration.rst
similarity index 100%
rename from Cabal/doc/nix-integration.rst
rename to doc/nix-integration.rst
diff --git a/Cabal/doc/nix-local-build-overview.rst b/doc/nix-local-build-overview.rst
similarity index 100%
rename from Cabal/doc/nix-local-build-overview.rst
rename to doc/nix-local-build-overview.rst
diff --git a/Cabal/doc/nix-local-build.rst b/doc/nix-local-build.rst
similarity index 100%
rename from Cabal/doc/nix-local-build.rst
rename to doc/nix-local-build.rst
diff --git a/Cabal/doc/references.inc b/doc/references.inc
similarity index 100%
rename from Cabal/doc/references.inc
rename to doc/references.inc
diff --git a/Cabal/doc/requirements.txt b/doc/requirements.txt
similarity index 100%
rename from Cabal/doc/requirements.txt
rename to doc/requirements.txt
diff --git a/Cabal/doc/setup-commands.rst b/doc/setup-commands.rst
similarity index 100%
rename from Cabal/doc/setup-commands.rst
rename to doc/setup-commands.rst