Skip to content

Commit 5ee43c8

Browse files
phadejphadej
authored
Merge pull request #6954 from phadej/doc-python-3b
Doc python 3b
2 parents 2b668ff + a4f9cf0 commit 5ee43c8

File tree

10 files changed

+83
-28
lines changed

10 files changed

+83
-28
lines changed

‎.readthedocs.yml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,6 @@ sphinx:
44
configuration: Cabal/doc/conf.py
55

66
python:
7-
version: 2.7
7+
version: 3.7
8+
install:
9+
- requirements: Cabal/doc/requirements.txt

‎Cabal/Makefile

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,16 +53,17 @@ $(HADDOCK_STAMP) : $(CONFIG_STAMP) $(BUILD_STAMP)
5353

5454
SPHINX_HTML_OUTDIR=dist/doc/users-guide
5555

56+
# do pip install everytime so we have up to date requirements when we build
5657
users-guide: .python-sphinx-virtualenv $(USERGUIDE_STAMP)
5758
$(USERGUIDE_STAMP) : doc/*.rst
5859
mkdir -p $(SPHINX_HTML_OUTDIR)
59-
(. ./.python-sphinx-virtualenv/bin/activate && $(SPHINXCMD) doc $(SPHINX_HTML_OUTDIR))
60+
(. ./.python-sphinx-virtualenv/bin/activate && pip install -r doc/requirements.txt && $(SPHINXCMD) doc $(SPHINX_HTML_OUTDIR))
6061

6162
docs: haddock users-guide
6263

6364
.python-sphinx-virtualenv:
64-
virtualenv .python-sphinx-virtualenv
65-
(. ./.python-sphinx-virtualenv/bin/activate && pip install sphinx && pip install sphinx_rtd_theme)
65+
python3 -m venv .python-sphinx-virtualenv
66+
(. ./.python-sphinx-virtualenv/bin/activate)
6667

6768
clean:
6869
rm -rf dist/

‎Cabal/doc/README.md

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,16 +11,11 @@ http://cabal.readthedocs.io/
1111

1212
### How to build it
1313

14-
* Currently requires python-2
15-
* `> pip install sphinx`
16-
* `> pip install sphinx_rtd_theme`
14+
Building the documentation requires Python 3 be installed
1715
* `> cd Cabal`
1816
* `> make clean users-guide`
19-
* if you are missing any other dependencies, install them with `pip` as needed
20-
¯\\\_(ツ)_/¯
2117
* Python on Mac OS X dislikes `LC_CTYPE=UTF-8`, unset the env var in
2218
terminal preferences and instead set `LC_ALL=en_US.UTF-8` or something
23-
* On archlinux, package `python2-sphinx` is sufficient.
2419

2520
### Caveats, for newcomers to RST from MD
2621
RST does not allow you to skip section levels when nesting, like MD

‎Cabal/doc/buildinfo-fields-reference.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -632,21 +632,21 @@ Test-suite fields
632632

633633
main-is
634634
* Optional field
635-
* Documentation of :pkg-field:`main-is`
635+
* Documentation of :pkg-field:`test-suite:main-is`
636636

637637
.. math::
638638
\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
639639
640640
test-module
641641
* Optional field
642-
* Documentation of :pkg-field:`test-module`
642+
* Documentation of :pkg-field:`test-suite:test-module`
643643

644644
.. math::
645645
{\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{"}}}
646646
647647
type
648648
* Optional field
649-
* Documentation of :pkg-field:`type`
649+
* Documentation of :pkg-field:`test-suite:type`
650650

651651
.. math::
652652
\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

Lines changed: 53 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1623,7 +1623,7 @@ system-dependent values for these fields.
16231623
The subtle but important difference in signaling allows tooling to
16241624
treat explicitly expressed ``<``-style constraints and inferred
16251625
(``^>=``-style) upper bounds differently. For instance,
1626-
:option:`--allow-newer`'s ``^``-modifier allows to relax only
1626+
:cfg-field:`allow-newer`'s ``^``-modifier allows to relax only
16271627
``^>=``-style bounds while leaving explicitly stated
16281628
``<``-constraints unaffected.
16291629

@@ -1725,6 +1725,7 @@ system-dependent values for these fields.
17251725
compiled twice, once as part of the library and again for the executable.
17261726

17271727
.. pkg-field:: default-extensions: identifier list
1728+
:since: 1.12
17281729

17291730
A list of Haskell extensions used by every module. These determine
17301731
corresponding compiler options enabled for all files. Extension
@@ -1734,6 +1735,7 @@ system-dependent values for these fields.
17341735
to be preprocessed with a C preprocessor.
17351736

17361737
.. pkg-field:: other-extensions: identifier list
1738+
:since: 1.12
17371739

17381740
A list of Haskell extensions used by some (but not necessarily all)
17391741
modules. From GHC version 6.6 onward, these may be specified by
@@ -1761,6 +1763,16 @@ system-dependent values for these fields.
17611763
for information only, but it is recommended to replicate them in
17621764
:pkg-field:`other-extensions` declarations.
17631765

1766+
.. pkg-field:: default-language: identifier
1767+
:since: 1.12
1768+
1769+
TBW
1770+
1771+
.. pkg-field:: other-languages: identifier
1772+
:since: 1.12
1773+
1774+
TBW
1775+
17641776
.. pkg-field:: extensions: identifier list
17651777
:deprecated: 1.12
17661778
:removed: 3.0
@@ -1941,6 +1953,18 @@ system-dependent values for these fields.
19411953
ones specified via :pkg-field:`ghc-options`, and are passed to GHC during
19421954
both the compile and link phases.
19431955

1956+
.. pkg-field:: ghcjs-options: token list
1957+
1958+
Like :pkg-field:`ghc-options` but applies to GHCJS
1959+
1960+
.. pkg-field:: ghcjs-prof-options: token list
1961+
1962+
Like :pkg-field:`ghc-prof-options` but applies to GHCJS
1963+
1964+
.. pkg-field:: ghcjs-shared-options: token list
1965+
1966+
Like :pkg-field:`ghc-shared-options` but applies to GHCJS
1967+
19441968
.. pkg-field:: includes: filename list
19451969

19461970
A list of header files to be included in any compilations via C.
@@ -2057,6 +2081,14 @@ system-dependent values for these fields.
20572081

20582082
A list of directories to search for libraries.
20592083

2084+
.. pkg-field:: extra-library-flavours: notsure
2085+
2086+
TBW
2087+
2088+
.. pkg-field:: extra-dynamic-library-flavours: notsure
2089+
2090+
TBW
2091+
20602092
.. pkg-field:: cc-options: token list
20612093

20622094
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.
26162648

26172649
The name `import` was chosen, because there is ``includes`` field.
26182650

2651+
.. pkg-section:: None
2652+
2653+
.. pkg-field:: import: token-list
2654+
2655+
TBW
2656+
26192657
Source Repositories
26202658
^^^^^^^^^^^^^^^^^^^
26212659

@@ -2883,6 +2921,8 @@ is to distinguish ``Cabal < 2.0`` from ``Cabal >= 2.0``.
28832921
Autogenerated modules and includes
28842922
----------------------------------
28852923

2924+
.. pkg-section:: None
2925+
28862926
Modules that are built automatically at setup, created with a custom
28872927
setup script, must appear on :pkg-field:`other-modules` for the library,
28882928
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
29332973
(e.g. by a ``configure`` script). Autogenerated header files are not
29342974
packaged by ``sdist`` command.
29352975

2976+
Virtual modules
2977+
---------------
2978+
2979+
TBW
2980+
2981+
.. pkg-field:: virtual-modules: module list
2982+
:since: 2.2
2983+
2984+
TBW
2985+
2986+
2987+
29362988
Accessing data files from package code
29372989
--------------------------------------
29382990

‎Cabal/doc/cabal-project.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@ Formally, the format is described by the following BNF:
143143
144144
145145
Specifying Packages from Remote Version Control Locations
146-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
146+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
147147

148148
Starting with Cabal 2.4, there is now a stanza
149149
``source-repository-package`` for specifying packages from an external

‎Cabal/doc/cabaldomain.py

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@
122122
from sphinx.directives import ObjectDescription
123123
from sphinx.domains import ObjType, Domain, Index
124124
from sphinx.domains.std import StandardDomain
125-
from sphinx.locale import l_, _
125+
from sphinx.locale import _
126126
from sphinx.roles import XRefRole
127127
from sphinx.util.docfields import Field, DocFieldTransformer
128128
from sphinx.util.nodes import make_refnode
@@ -150,7 +150,7 @@ def parse_flag(env, sig, signode):
150150
name = parts[0]
151151
names.append(name)
152152
sig = sep + ' '.join(parts[1:])
153-
sig = re.sub(ur'<([-a-zA-Z ]+)>', ur'⟨\1⟩', sig)
153+
sig = re.sub(r'<([-a-zA-Z ]+)>', r'⟨\1⟩', sig)
154154
if i > 0:
155155
signode += addnodes.desc_name(', ', ', ')
156156
signode += addnodes.desc_name(name, name)
@@ -200,7 +200,7 @@ def find_section_title(parent):
200200
if isinstance(kid, nodes.title):
201201
return kid.astext(), section_id
202202

203-
print section_name, section_id
203+
print(section_name, section_id)
204204
return section_name, section_id
205205

206206

@@ -813,10 +813,10 @@ class CabalDomain(Domain):
813813
name = 'cabal'
814814
label = 'Cabal'
815815
object_types = {
816-
'pkg-section': ObjType(l_('pkg-section'), 'pkg-section'),
817-
'pkg-field' : ObjType(l_('pkg-field') , 'pkg-field' ),
818-
'cfg-section': ObjType(l_('cfg-section'), 'cfg-section'),
819-
'cfg-field' : ObjType(l_('cfg-field') , 'cfg-field' ),
816+
'pkg-section': ObjType(_('pkg-section'), 'pkg-section'),
817+
'pkg-field' : ObjType(_('pkg-field') , 'pkg-field' ),
818+
'cfg-section': ObjType(_('cfg-section'), 'cfg-section'),
819+
'cfg-field' : ObjType(_('cfg-field') , 'cfg-field' ),
820820
}
821821
directives = {
822822
'pkg-section': CabalPackageSection,
@@ -853,9 +853,12 @@ class CabalDomain(Domain):
853853
def clear_doc(self, docname):
854854
for k in ['pkg-sections', 'pkg-fields', 'cfg-sections',
855855
'cfg-fields', 'cfg-flags']:
856+
to_del = []
856857
for name, (fn, _, _) in self.data[k].items():
857858
if fn == docname:
858-
del self.data[k][name]
859+
to_del.append(name)
860+
for name in to_del:
861+
del self.data[k][name]
859862
try:
860863
del self.data['index-num'][docname]
861864
except KeyError:
@@ -910,5 +913,5 @@ class CabalLexer(lexer.RegexLexer):
910913

911914
def setup(app):
912915
app.add_domain(CabalDomain)
913-
app.add_lexer('cabal', CabalLexer())
916+
app.add_lexer('cabal', CabalLexer)
914917

‎Cabal/doc/conf.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434

3535
# General information about the project.
3636
project = u'Cabal'
37-
copyright = u'2003-2017, Cabal Team'
37+
copyright = u'2003-2020, Cabal Team'
3838
# N.B. version comes from ghc_config
3939
release = version # The full version, including alpha/beta/rc tags.
4040

@@ -99,7 +99,7 @@
9999
latex_elements = {
100100
'inputenc': '',
101101
'utf8extra': '',
102-
'preamble': '''
102+
'preamble': r'''
103103
\usepackage{fontspec}
104104
\usepackage{makeidx}
105105
\setsansfont{DejaVu Sans}
@@ -174,7 +174,7 @@ def parse_flag(env, sig, signode):
174174
name = parts[0]
175175
names.append(name)
176176
sig = sep + ' '.join(parts[1:])
177-
sig = re.sub(ur'<([-a-zA-Z ]+)>', ur'⟨\1⟩', sig)
177+
sig = re.sub(r'<([-a-zA-Z ]+)>', r'⟨\1⟩', sig)
178178
if i > 0:
179179
signode += addnodes.desc_name(', ', ', ')
180180
signode += addnodes.desc_name(name, name)

‎Cabal/doc/requirements.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
sphinx == 3.1.*
2+
sphinx_rtd_theme

‎buildinfo-reference-generator/template.zinza

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -221,7 +221,7 @@ Test-suite fields
221221
{# We show documentation link only for non deprecated fields #}
222222
{% if null field.deprecatedSince.fst %}
223223
{% if null field.removedIn.fst %}
224-
* Documentation of :pkg-field:`{{field.name}}`
224+
* Documentation of :pkg-field:`test-suite:{{field.name}}`
225225
{% endif %}
226226
{% endif %}
227227
{% if notNull field.syntax %}

0 commit comments

Comments
 (0)