Commit 4d72925a authored by Luke Lau's avatar Luke Lau Committed by Oleg Grenrus

Update docs to build with python 3

Also fix some deprecated Sphinx stuff and update building documentation
to mention the virtualenv

Use a requirements file to specify sphinx version

Use the builtin python3 virtualenv

Saves one more dependency you need to install!
https://docs.python.org/3/tutorial/venv.html
parent 2b668ff1
......@@ -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
......
......@@ -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.
......@@ -100,11 +100,11 @@ latex_elements = {
'inputenc': '',
'utf8extra': '',
'preamble': '''
\usepackage{fontspec}
\usepackage{makeidx}
\setsansfont{DejaVu Sans}
\setromanfont{DejaVu Serif}
\setmonofont{DejaVu Sans Mono}
\\usepackage{fontspec}
\\usepackage{makeidx}
\\setsansfont{DejaVu Sans}
\\setromanfont{DejaVu Serif}
\\setmonofont{DejaVu Sans Mono}
''',
}
......@@ -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
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