Merge pull request #3390 from mmerickel/whatsnew-1.10

Michael Merickel

2018-10-16 8eed333343e4e9e7f11f3aee67299030d6bf2783

 docs/conf.py

@@ -20,6 +20,7 @@
warnings.simplefilter('ignore', DeprecationWarning)

import pkg_resources
import pylons_sphinx_themes

# skip raw nodes
from sphinx.writers.text import TextTranslator
@@ -48,46 +49,40 @@
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
    'repoze.sphinx.autointerface',
    'sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'repoze.sphinx.autointerface',
    'sphinx.ext.intersphinx',
    'sphinx.ext.viewcode',
    'sphinx.ext.intersphinx'
    'sphinxcontrib.autoprogram',
    # enable pylons_sphinx_latesturl when this branch is no longer "latest"
    # 'pylons_sphinx_latesturl',
    ]

# Looks for objects in external projects
intersphinx_mapping = {
    'tutorials': ('http://docs.pylonsproject.org/projects/pyramid-tutorials/en/latest/', None),
    'cookbook': ('http://docs.pylonsproject.org/projects/pyramid-cookbook/en/latest/', None),
    'jinja2': ('http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/', None),
    'tm': (
        'http://docs.pylonsproject.org/projects/pyramid_tm/en/latest/',
        None,
    ),
    'zcomponent': ('http://docs.zope.org/zope.component', None),
    'colander': ('https://docs.pylonsproject.org/projects/colander/en/latest', None),
    'cookbook': ('https://docs.pylonsproject.org/projects/pyramid-cookbook/en/latest/', None),
    'cookiecutter': ('https://cookiecutter.readthedocs.io/en/latest/', None),
    'deform': ('https://docs.pylonsproject.org/projects/deform/en/latest', None),
    'jinja2': ('https://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/', None),
    'plaster': ('https://docs.pylonsproject.org/projects/plaster/en/latest/', None),
    'pylonswebframework': ('https://docs.pylonsproject.org/projects/pylons-webframework/en/latest/', None),
    'python': ('https://docs.python.org/3', None),
    'pytest': ('https://docs.pytest.org/en/latest/', None),
    'sphinx': ('http://www.sphinx-doc.org/en/latest', None),
    'sqla': ('https://docs.sqlalchemy.org/en/latest', None),
    'tm': ('https://docs.pylonsproject.org/projects/pyramid-tm/en/latest/', None),
    'toolbar': ('https://docs.pylonsproject.org/projects/pyramid-debugtoolbar/en/latest', None),
    'tstring': ('https://docs.pylonsproject.org/projects/translationstring/en/latest', None),
    'tutorials': ('https://docs.pylonsproject.org/projects/pyramid-tutorials/en/latest/', None),
    'venusian': ('https://docs.pylonsproject.org/projects/venusian/en/latest', None),
    'webob': ('https://docs.pylonsproject.org/projects/webob/en/latest/', None),
    'webtest': ('http://webtest.pythonpaste.org/en/latest', None),
    'webob': ('http://docs.webob.org/en/latest', None),
    'colander': (
        'http://docs.pylonsproject.org/projects/colander/en/latest',
    None),
    'deform': (
        'http://docs.pylonsproject.org/projects/deform/en/latest',
    None),
    'sqla': ('http://docs.sqlalchemy.org/en/latest', None),
    'who': ('http://docs.repoze.org/who/latest', None),
    'python': ('http://docs.python.org', None),
    'python3': ('http://docs.python.org/3', None),
    'tstring':
        ('http://docs.pylonsproject.org/projects/translationstring/en/latest',
          None),
    'venusian':
        ('http://docs.pylonsproject.org/projects/venusian/en/latest', None),
    'toolbar':
        ('http://docs.pylonsproject.org/projects/pyramid-debugtoolbar/en/latest',
         None),
    'zcml':
        ('http://docs.pylonsproject.org/projects/pyramid-zcml/en/latest',
         None),
    'who': ('https://repozewho.readthedocs.io/en/latest', None),
    'zcml': ('https://docs.pylonsproject.org/projects/pyramid-zcml/en/latest', None),
    'zcomponent': ('https://zopecomponent.readthedocs.io/en/latest/', None),
    'zinterface': ('https://zopeinterface.readthedocs.io/en/latest/', None),
}


@@ -135,32 +130,45 @@

# Options for HTML output
# -----------------------
# enable pylons_sphinx_latesturl when this branch is no longer "latest"
# pylons_sphinx_latesturl_base = (
#     'https://docs.pylonsproject.org/projects/pyramid/en/latest/')
# pylons_sphinx_latesturl_pagename_overrides = {
#     # map old pagename -> new pagename
#     'whatsnew-1.0': 'index',
#     'whatsnew-1.1': 'index',
#     'whatsnew-1.2': 'index',
#     'whatsnew-1.3': 'index',
#     'whatsnew-1.4': 'index',
#     'whatsnew-1.5': 'index',
#     'whatsnew-1.6': 'index',
#     'whatsnew-1.7': 'index',
#     'whatsnew-1.8': 'index',
#     'whatsnew-1.9': 'index',
#     'tutorials/gae/index': 'index',
#     'api/chameleon_text': 'api',
#     'api/chameleon_zpt': 'api',
# }

# Add and use Pylons theme
if 'sphinx-build' in ' '.join(sys.argv):  # protect against dumb importers
    from subprocess import call, Popen, PIPE
    cwd = os.getcwd()
    p = Popen('which git', shell=True, stdout=PIPE)
    here = os.path.abspath(os.path.dirname(__file__))
    parent = os.path.abspath(os.path.dirname(here))
    _themes = os.path.join(here, '_themes')
    git = p.stdout.read().strip()
    try:
        os.chdir(parent)
        if not os.listdir(_themes):
            call([git, 'submodule', '--init'])
        else:
            call([git, 'submodule', 'update'])
        sys.path.append(_themes)
    finally:
        os.chdir(cwd)

html_theme_path = ['_themes']
html_theme = 'pyramid'
html_theme_path = pylons_sphinx_themes.get_html_themes_path()
html_theme_options = dict(
    github_url='https://github.com/Pylons/pyramid',
    # On master branch and new branch still in
    # pre-release status: true; else: false.
    in_progress='true',
    # On branches previous to "latest": true; else: false.
    outdated='false',
    )

# Control display of sidebars
html_sidebars = {'**': [
    'localtoc.html',
    'ethicalads.html',
    'relations.html',
    'sourcelink.html',
    'searchbox.html',
]}

# The name for this set of Sphinx documents.  If None, it defaults to
# "<project> v<release> documentation".
@@ -170,9 +178,8 @@
# using the given strftime format.
html_last_updated_fmt = '%b %d, %Y'

# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
html_use_smartypants = False # people use cutnpaste in some places
# Do not use smart quotes.
smartquotes = False

# Output file base name for HTML help builder.
htmlhelp_basename = 'pyramid'
@@ -186,7 +193,10 @@
# The font size ('10pt', '11pt' or '12pt').
latex_font_size = '10pt'

latex_additional_files = ['_static/latex-note.png', '_static/latex-warning.png']
latex_additional_files = [
    '_static/latex-note.png',
    '_static/latex-warning.png',
]

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, document class [howto/manual]).
@@ -198,10 +208,10 @@

# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
latex_use_parts = True
latex_toplevel_sectioning = "section"

# If false, no module index is generated.
latex_use_modindex = False
latex_domain_indices = False

## Say, for a moment that you have a twoside document that needs a 3cm
## inner margin to allow for binding and at least two centimetres the
@@ -216,6 +226,17 @@
_PREAMBLE = r"""
\usepackage[]{geometry}
\geometry{bindingoffset=0.45in,textheight=7.25in,hdivide={0.5in,*,0.75in},vdivide={1in,7.25in,1in},papersize={7.5in,9.25in}}

%XeLaTeX packages
\usepackage{xltxtra}
\usepackage{fontspec} %Font package
\usepackage{xunicode}

%Select fonts
\setmainfont[Mapping=tex-text]{nimbusserif}
\setsansfont[Mapping=tex-text]{nimbussans}
\setmonofont{nimbusmono}

\hypersetup{
    colorlinks=true,
    linkcolor=black,
@@ -272,28 +293,22 @@
\definecolor{VerbatimColor}{rgb}{1,1,1}
\definecolor{VerbatimBorderColor}{rgb}{1,1,1}

\makeatletter
\renewcommand{\py@noticestart@warning}{\py@heavybox}
\renewcommand{\py@noticeend@warning}{\py@endheavybox}
\renewcommand{\py@noticestart@note}{\py@heavybox}
\renewcommand{\py@noticeend@note}{\py@endheavybox}
\makeatother

% icons in note and warning boxes
\usepackage{ifthen}
% Keep a copy of the original notice environment
\let\origbeginnotice\notice
\let\origendnotice\endnotice

% Redefine the notice environment so we can add our own code to it
\renewenvironment{notice}[2]{%
  \origbeginnotice{#1}{}% equivalent to original \begin{notice}{#1}{#2}
% Keep a copy of the original sphinxadmonition environment
\let\origbeginadmon\sphinxadmonition
\let\origendadmon\endsphinxadmonition

% Redefine the sphinxadmonition environment so we can add our own code to it
\renewenvironment{sphinxadmonition}[2]{%
  \origbeginadmon{#1}{}% equivalent to original \begin{sphinxadmonition}{#1}{#2}
  % load graphics
  \ifthenelse{\equal{#1}{warning}}{\includegraphics{latex-warning.png}}{}
  \ifthenelse{\equal{#1}{note}}{\includegraphics{latex-note.png}}{}
  % etc.
}{%
  \origendnotice% equivalent to original \end{notice}
  }{%
\origendadmon % equivalent to original \end{sphinxadmonition}
}

% try to prevent code-block boxes from splitting across pages
@@ -314,7 +329,6 @@

latex_elements = {
    'preamble': _PREAMBLE,
    'wrapperclass': 'book',
    'date': '',
    'releasename': 'Version',
    'title': r'The Pyramid Web Framework',
@@ -338,17 +352,6 @@
                content_offset, block_text, state, state_machine):
    return [nodes.raw(
        '',
        r"""
\frontmatter
% prevent part/chapter/section numbering
\setcounter{secnumdepth}{-2}
% suppress headers
\pagestyle{plain}
% reset page counter
\setcounter{page}{1}
% suppress first toc pagenum
\addtocontents{toc}{\protect\thispagestyle{empty}}
""",
        format='latex')]


@@ -356,26 +359,14 @@
               content_offset, block_text, state, state_machine):
    return [nodes.raw(
        '',
        r"""
\mainmatter
% allow part/chapter/section numbering
\setcounter{secnumdepth}{2}
% get headers back
\pagestyle{fancy}
\fancyhf{}
\renewcommand{\headrulewidth}{0.5pt}
\renewcommand{\footrulewidth}{0pt}
\fancyfoot[C]{\thepage}
\fancyhead[RO]{\rightmark}
\fancyhead[LE]{\leftmark}
""",
        format='latex')]


def backmatter(name, arguments, options, content, lineno,
              content_offset, block_text, state, state_machine):
    return [nodes.raw('', '\\backmatter\n\\setcounter{secnumdepth}{-1}\n',
                      format='latex')]
    return [nodes.raw(
        '',
        format='latex')]


def app_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
@@ -453,3 +444,11 @@
epub_tocdepth = 3

# For a list of all settings, visit http://sphinx-doc.org/config.html

# -- Options for linkcheck builder -------------------------------------------

# List of items to ignore when running linkcheck
linkcheck_ignore = [
    r'http://localhost:\d+',
    r'http://localhost',
]