Commit 5ee43c8f authored by Oleg Grenrus's avatar Oleg Grenrus Committed by GitHub

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

Doc python 3b
parents 2b668ff1 a4f9cf0b
......@@ -4,4 +4,6 @@ sphinx:
configuration: Cabal/doc/conf.py
python:
version: 2.7
version: 3.7
install:
- requirements: Cabal/doc/requirements.txt
......@@ -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/
......
......@@ -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
......
......@@ -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\}
......
......@@ -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
--------------------------------------
......
......@@ -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
......
......@@ -122,7 +122,7 @@ from sphinx import addnodes
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)
......@@ -34,7 +34,7 @@ extlinks = {
# 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 @@ mathjax_path = 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?c
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)
......
sphinx == 3.1.*
sphinx_rtd_theme
......@@ -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 %}
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment