Merge pull request #6954 from phadej/doc-python-3b

Doc python 3b

Author: phadej

.readthedocs.yml

@@ -4,4 +4,6 @@ sphinx:
   configuration: Cabal/doc/conf.py
 
 python:
-  version: 2.7
+  version: 3.7
+  install:
+    - requirements: Cabal/doc/requirements.txt

Cabal/Makefile

@@ -53,16 +53,17 @@ $(HADDOCK_STAMP) : $(CONFIG_STAMP) $(BUILD_STAMP)
 
 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 && $(SPHINXCMD) doc $(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:
-	virtualenv .python-sphinx-virtualenv
-	(. ./.python-sphinx-virtualenv/bin/activate && pip install sphinx && pip install sphinx_rtd_theme)
+	python3 -m venv .python-sphinx-virtualenv
+	(. ./.python-sphinx-virtualenv/bin/activate)
 
 clean:
 	rm -rf dist/

Cabal/doc/README.md

@@ -11,16 +11,11 @@ http://cabal.readthedocs.io/
 
 ### How to build it
 
-* Currently requires python-2
-* `> pip install sphinx`
-* `> pip install sphinx_rtd_theme`
+Building the documentation requires Python 3 be installed
 * `> cd Cabal`
 * `> make clean users-guide`
-* if you are missing any other dependencies, install them with `pip` as needed
-¯\\\_(ツ)_/¯
 * Python on Mac OS X dislikes `LC_CTYPE=UTF-8`, unset the env var in
 terminal preferences and instead set `LC_ALL=en_US.UTF-8` or something
-* On archlinux, package `python2-sphinx` is sufficient.
 
 ### Caveats, for newcomers to RST from MD
 RST does not allow you to skip section levels when nesting, like MD

Cabal/doc/buildinfo-fields-reference.rst

@@ -632,21 +632,21 @@ Test-suite fields
 
 main-is
     * Optional field
-    * Documentation of :pkg-field:`main-is`
+    * Documentation of :pkg-field:`test-suite:main-is`
 
     .. math::
         \left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 
 test-module
     * Optional field
-    * Documentation of :pkg-field:`test-module`
+    * Documentation of :pkg-field:`test-suite:test-module`
 
     .. math::
         {\left(\mathop{\mathit{upper}}{\left\{ \mathop{\mathit{alpha\text{-}num}}\mid[\mathop{\mathord{``}\mathtt{\text{'}}\mathord{"}}\mathop{\mathord{``}\mathtt{\text{_}}\mathord{"}}] \right\}}^\ast_{}\right)}^+_{\mathop{\mathord{``}\mathtt{\text{.}}\mathord{"}}}
 
 type
     * Optional field
-    * Documentation of :pkg-field:`type`
+    * Documentation of :pkg-field:`test-suite:type`
 
     .. math::
         \left\{ \mathop{\mathord{``}\mathtt{exitcode\text{-}stdio\text{-}1\text{.}0}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{detailed\text{-}0\text{.}9}\mathord{"}} \right\}

Cabal/doc/cabal-package.rst

@@ -1623,7 +1623,7 @@ system-dependent values for these fields.
     The subtle but important difference in signaling allows tooling to
     treat explicitly expressed ``<``-style constraints and inferred
     (``^>=``-style) upper bounds differently.  For instance,
-    :option:`--allow-newer`'s ``^``-modifier allows to relax only
+    :cfg-field:`allow-newer`'s ``^``-modifier allows to relax only
     ``^>=``-style bounds while leaving explicitly stated
     ``<``-constraints unaffected.
 
@@ -1725,6 +1725,7 @@ system-dependent values for these fields.
       compiled twice, once as part of the library and again for the executable.
 
 .. pkg-field:: default-extensions: identifier list
+   :since: 1.12
 
     A list of Haskell extensions used by every module. These determine
     corresponding compiler options enabled for all files. Extension
@@ -1734,6 +1735,7 @@ system-dependent values for these fields.
     to be preprocessed with a C preprocessor.
 
 .. pkg-field:: other-extensions: identifier list
+   :since: 1.12
 
     A list of Haskell extensions used by some (but not necessarily all)
     modules. From GHC version 6.6 onward, these may be specified by
@@ -1761,6 +1763,16 @@ system-dependent values for these fields.
     for information only, but it is recommended to replicate them in
     :pkg-field:`other-extensions` declarations.
 
+.. pkg-field:: default-language: identifier
+   :since: 1.12
+
+   TBW
+
+.. pkg-field:: other-languages: identifier
+   :since: 1.12
+
+   TBW
+
 .. pkg-field:: extensions: identifier list
    :deprecated: 1.12
    :removed: 3.0
@@ -1941,6 +1953,18 @@ system-dependent values for these fields.
     ones specified via :pkg-field:`ghc-options`, and are passed to GHC during
     both the compile and link phases.
 
+.. pkg-field:: ghcjs-options: token list
+
+   Like :pkg-field:`ghc-options` but applies to GHCJS
+
+.. pkg-field:: ghcjs-prof-options: token list
+
+   Like :pkg-field:`ghc-prof-options` but applies to GHCJS
+
+.. pkg-field:: ghcjs-shared-options: token list
+
+   Like :pkg-field:`ghc-shared-options` but applies to GHCJS
+
 .. pkg-field:: includes: filename list
 
     A list of header files to be included in any compilations via C.
@@ -2057,6 +2081,14 @@ system-dependent values for these fields.
 
     A list of directories to search for libraries.
 
+.. pkg-field:: extra-library-flavours: notsure
+
+    TBW
+
+.. pkg-field:: extra-dynamic-library-flavours: notsure
+
+    TBW
+
 .. pkg-field:: cc-options: token list
 
     Command-line arguments to be passed to the C compiler. Since the
@@ -2616,6 +2648,12 @@ Starting with Cabal-2.2 it's possible to use common build info stanzas.
 
     The name `import` was chosen, because there is ``includes`` field.
 
+.. pkg-section:: None
+
+.. pkg-field:: import: token-list
+
+    TBW
+
 Source Repositories
 ^^^^^^^^^^^^^^^^^^^
 
@@ -2883,6 +2921,8 @@ is to distinguish ``Cabal < 2.0`` from ``Cabal >= 2.0``.
 Autogenerated modules and includes
 ----------------------------------
 
+.. pkg-section:: None
+
 Modules that are built automatically at setup, created with a custom
 setup script, must appear on :pkg-field:`other-modules` for the library,
 executable, test-suite or benchmark stanzas or also on
@@ -2933,6 +2973,18 @@ Right now :pkg-field:`executable:main-is` modules are not supported on
    (e.g. by a ``configure`` script). Autogenerated header files are not
    packaged by ``sdist`` command.
 
+Virtual modules
+---------------
+
+TBW
+
+.. pkg-field:: virtual-modules: module list
+   :since: 2.2
+
+   TBW
+
+
+
 Accessing data files from package code
 --------------------------------------
 

Cabal/doc/cabal-project.rst

@@ -143,7 +143,7 @@ Formally, the format is described by the following BNF:
 
 
 Specifying Packages from Remote Version Control Locations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Starting with Cabal 2.4, there is now a stanza
 ``source-repository-package`` for specifying packages from an external

Cabal/doc/cabaldomain.py

@@ -122,7 +122,7 @@
 from sphinx.directives import ObjectDescription
 from sphinx.domains import ObjType, Domain, Index
 from sphinx.domains.std import StandardDomain
-from sphinx.locale import l_, _
+from sphinx.locale import _
 from sphinx.roles import XRefRole
 from sphinx.util.docfields import Field, DocFieldTransformer
 from sphinx.util.nodes import make_refnode
@@ -150,7 +150,7 @@ def parse_flag(env, sig, signode):
         name = parts[0]
         names.append(name)
         sig = sep + ' '.join(parts[1:])
-        sig = re.sub(ur'<([-a-zA-Z ]+)>', ur'⟨\1⟩', sig)
+        sig = re.sub(r'<([-a-zA-Z ]+)>', r'⟨\1⟩', sig)
         if i > 0:
             signode += addnodes.desc_name(', ', ', ')
         signode += addnodes.desc_name(name, name)
@@ -200,7 +200,7 @@ def find_section_title(parent):
         if isinstance(kid, nodes.title):
             return kid.astext(), section_id
 
-    print section_name, section_id
+    print(section_name, section_id)
     return section_name, section_id
 
 
@@ -813,10 +813,10 @@ class CabalDomain(Domain):
     name = 'cabal'
     label = 'Cabal'
     object_types = {
-        'pkg-section': ObjType(l_('pkg-section'), 'pkg-section'),
-        'pkg-field'  : ObjType(l_('pkg-field')  , 'pkg-field'  ),
-        'cfg-section': ObjType(l_('cfg-section'), 'cfg-section'),
-        'cfg-field'  : ObjType(l_('cfg-field')  , 'cfg-field' ),
+        'pkg-section': ObjType(_('pkg-section'), 'pkg-section'),
+        'pkg-field'  : ObjType(_('pkg-field')  , 'pkg-field'  ),
+        'cfg-section': ObjType(_('cfg-section'), 'cfg-section'),
+        'cfg-field'  : ObjType(_('cfg-field')  , 'cfg-field' ),
     }
     directives = {
         'pkg-section': CabalPackageSection,
@@ -853,9 +853,12 @@ class CabalDomain(Domain):
     def clear_doc(self, docname):
         for k in ['pkg-sections', 'pkg-fields', 'cfg-sections',
                   'cfg-fields', 'cfg-flags']:
+            to_del = []
             for name, (fn, _, _) in self.data[k].items():
                 if fn == docname:
-                    del self.data[k][name]
+                    to_del.append(name)
+            for name in to_del:
+                del self.data[k][name]
         try:
             del self.data['index-num'][docname]
         except KeyError:
@@ -910,5 +913,5 @@ class CabalLexer(lexer.RegexLexer):
 
 def setup(app):
     app.add_domain(CabalDomain)
-    app.add_lexer('cabal', CabalLexer())
+    app.add_lexer('cabal', CabalLexer)
 

Cabal/doc/conf.py

@@ -34,7 +34,7 @@
 
 # General information about the project.
 project = u'Cabal'
-copyright = u'2003-2017, Cabal Team'
+copyright = u'2003-2020, Cabal Team'
 # N.B. version comes from ghc_config
 release = version  # The full version, including alpha/beta/rc tags.
 
@@ -99,7 +99,7 @@
 latex_elements = {
     'inputenc': '',
     'utf8extra': '',
-    'preamble': '''
+    'preamble': r'''
 \usepackage{fontspec}
 \usepackage{makeidx}
 \setsansfont{DejaVu Sans}
@@ -174,7 +174,7 @@ def parse_flag(env, sig, signode):
         name = parts[0]
         names.append(name)
         sig = sep + ' '.join(parts[1:])
-        sig = re.sub(ur'<([-a-zA-Z ]+)>', ur'⟨\1⟩', sig)
+        sig = re.sub(r'<([-a-zA-Z ]+)>', r'⟨\1⟩', sig)
         if i > 0:
             signode += addnodes.desc_name(', ', ', ')
         signode += addnodes.desc_name(name, name)

Cabal/doc/requirements.txt

@@ -0,0 +1,2 @@
+sphinx == 3.1.*
+sphinx_rtd_theme

buildinfo-reference-generator/template.zinza

@@ -221,7 +221,7 @@ Test-suite fields
 {# We show documentation link only for non deprecated fields #}
 {% if null field.deprecatedSince.fst %}
 {% if null field.removedIn.fst %}
-    * Documentation of :pkg-field:`{{field.name}}`
+    * Documentation of :pkg-field:`test-suite:{{field.name}}`
 {% endif %}
 {% endif %}
 {% if notNull field.syntax %}