Merge pull request #9379 from malteneuss/top-level-guides-and-reference

Restructure user guide into top-level guides, reference and explanation parts

Author: mergify[bot]

.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

@@ -25,7 +25,7 @@
 templates_path = ['_templates']
 source_suffix = '.rst'
 source_encoding = 'utf-8-sig'
-master_doc = 'index'
+root_doc = 'index'
 
 # extlinks -- see http://www.sphinx-doc.org/en/stable/ext/extlinks.html
 extlinks = {