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

…reference Restructure user guide into top-level guides, reference and explanation parts
mpickering · Nov 5, 2023 · 2fca50b · 2fca50b
2 parents 7691c45 + 759ba8e
commit 2fca50b
Show file tree

Hide file tree

Showing 18 changed files with 350 additions and 420 deletions.
diff --git a/.gitignore b/.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

diff --git a/doc/_templates/layout.html b/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 %}
-
diff --git a/doc/bugs-and-stability.rst b/doc/bugs-and-stability.rst
diff --git a/doc/intro.rst → doc/cabal-context.rst b/doc/intro.rst → doc/cabal-context.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
 ----------------

diff --git a/doc/misc.rst → doc/cabal-interface-stability.rst b/doc/misc.rst → doc/cabal-interface-stability.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
-libraries@haskell.org. There is also a development mailing list
-cabal-devel@haskell.org.
-
 Stability of Cabal interfaces
 =============================
 

diff --git a/doc/cabal-package.rst → doc/cabal-package-description-file.rst b/doc/cabal-package.rst → doc/cabal-package-description-file.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:
 

diff --git a/doc/cabal-project.rst → doc/cabal-project-description-file.rst b/doc/cabal-project.rst → doc/cabal-project-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

diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
@@ -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):

diff --git a/doc/concepts-and-development.rst b/doc/concepts-and-development.rst
diff --git a/doc/conf.py b/doc/conf.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 = {

diff --git a/doc/getting-started.rst b/doc/getting-started.rst
@@ -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.
diff --git a/doc/nix-local-build-overview.rst → doc/how-to-build-like-nix.rst b/doc/nix-local-build-overview.rst → doc/how-to-build-like-nix.rst
@@ -1,7 +1,7 @@
 .. _nix-style-builds:
 
-Nix-style Local Builds
-======================
+How to build locally like in Nix
+================================
 
 Nix-style local builds are a new build system implementation inspired by Nix.
 The Nix-style local build system is commonly called "v2-build" for short