Restructure Cabal documentation top-level parts

The goal is for users to easier find pages for typical problems through search engines and page navigation.
- The top-level layout is based on the popular documentation structure by https://documentation.divio.com/ to give a
   clear structure to users and future documentation contributors:
  * Guides: Present a solution to a single, atomic, typical user problem.
  * Reference: Describe user API (CLI fields, syntax etc) with technical rigour and completeness.
  * Explanation: Discuss background information, scope, design decisions etc.
- Move existing documentation roughly into these categories with minimal editing as the basis for further editing.
- Rename guide titles to mention how-to for improving SEO.
- Rename some files to improve SEO since that name becomes part of the URL (often called slug).
  Important page keywords should appear in the slug as well to make pages rank higher in search engines.

Author: malteneuss

.gitignore

@@ -73,6 +73,8 @@ cabal-testsuite/**/haddocks
 # python artifacts from documentation builds
 *.pyc
 .python-sphinx-virtualenv/
+venv
+.venv
 /doc/.skjold_cache/
 
 # macOS folder metadata

doc/_templates/layout.html

@@ -1,8 +1,7 @@
 {% extends "!layout.html" %}
 
 {% block menu %}
-  {{ super() }}
-  <a href="cabal-projectindex.html">Reference</a>
+{{ super() }}
+  <a href="cabal-syntax-quicklinks.html">Cabal Syntax Quicklinks</a>
   <a href="genindex.html">Index</a>
 {% endblock %}
-

doc/bugs-and-stability.rst

@@ -14,8 +14,8 @@ use Hackage_ which is Haskell's central
 package archive that contains thousands of libraries and applications in
 the Cabal package format.
 
-Introduction
-============
+What Cabal does
+===============
 
 Cabal is a package system for Haskell software. The point of a package
 system is to enable software developers and users to easily distribute,
@@ -122,7 +122,7 @@ the package depends on.
 
 For full details on what goes in the ``.cabal`` and ``Setup.hs`` files,
 and for all the other features provided by the build system, see the
-section on :doc:`developing packages <developing-packages>`.
+section on :doc:`How to package Haskell code <how-to-package-haskell-code>`.
 
 Cabal featureset
 ----------------

doc/intro.rst renamed to doc/cabal-context.rst

@@ -1,13 +1,3 @@
-Reporting bugs and deficiencies
-===============================
-
-Please report any flaws or feature requests in the `bug
-tracker <https://github.com/haskell/cabal/issues>`__.
-
-For general discussion or queries email the libraries mailing list
-[email protected]. There is also a development mailing list
-[email protected].
-
 Stability of Cabal interfaces
 =============================
 

doc/misc.rst renamed to doc/cabal-interface-stability.rst

@@ -1,6 +1,8 @@
-Package Description
-===================
+Package Description — <package>.cabal File
+==========================================
 
+The package description file, commonly known as "the Cabal file",
+describes the contents of a package.
 The Cabal package is the unit of distribution. When installed, its
 purpose is to make available:
 

doc/cabal-package.rst renamed to doc/cabal-package-description-file.rst

@@ -1,5 +1,5 @@
-cabal.project Reference
-=======================
+Project Description — cabal.project File
+========================================
 
 ``cabal.project`` files support a variety of options which configure the
 details of your build. The general syntax of a ``cabal.project`` file is

doc/cabal-project.rst renamed to doc/cabal-project-description-file.rst

@@ -598,9 +598,9 @@ class CabalConfigFieldXRef(CabalFieldXRef):
 #
 
 class ConfigFieldIndex(Index):
-    name = 'projectindex'
-    localname = "Cabal reference"
-    shortname = "Reference"
+    name = 'syntax-quicklinks'
+    localname = "Cabal Syntax Quicklinks"
+    shortname = "Quicklinks"
 
     class Entry(object):
         def __init__(self, typ, name, doc, anchor, meta):

doc/cabaldomain.py

@@ -228,4 +228,4 @@ What Next?
 Now that you know how to set up a simple Haskell package using Cabal, check out
 some of the resources on the Haskell website's `documentation page
 <https://www.haskell.org/documentation/>`__ or read more about packages and
-Cabal on the :doc:`introduction <intro>` page.
+Cabal on the :doc:`What Cabal does <cabal-context>` page.