From b0c6ca936d45c5b43d3253ae477959073f6399d7 Mon Sep 17 00:00:00 2001
From: Michael Droettboom <mdboom@gmail.com>
Date: Thu, 29 Oct 2015 14:40:58 -0400
Subject: [PATCH 1/2] Fix doc build
---
doc/_themes/pydoctheme/static/pydoctheme.css | 170 -------
doc/_themes/pydoctheme/theme.conf | 23 -
doc/source/_templates/autosummary/class.rst | 55 +-
doc/source/conf.py | 9 +-
doc/source/intro.rst | 2 +-
doc/sphinxext/__init__.py | 1 -
doc/sphinxext/docscrape.py | 505 -------------------
doc/sphinxext/docscrape_sphinx.py | 227 ---------
doc/sphinxext/numpydoc.py | 169 -------
docstrings/face.py | 4 +-
docstrings/outline.py | 4 +-
11 files changed, 40 insertions(+), 1129 deletions(-)
delete mode 100644 doc/_themes/pydoctheme/static/pydoctheme.css
delete mode 100644 doc/_themes/pydoctheme/theme.conf
delete mode 100644 doc/sphinxext/__init__.py
delete mode 100644 doc/sphinxext/docscrape.py
delete mode 100644 doc/sphinxext/docscrape_sphinx.py
delete mode 100644 doc/sphinxext/numpydoc.py
diff --git a/doc/_themes/pydoctheme/static/pydoctheme.css b/doc/_themes/pydoctheme/static/pydoctheme.css
deleted file mode 100644
index 9942ca6..0000000
--- a/doc/_themes/pydoctheme/static/pydoctheme.css
+++ /dev/null
@@ -1,170 +0,0 @@
-@import url("default.css");
-
-body {
- background-color: white;
- margin-left: 1em;
- margin-right: 1em;
-}
-
-div.related {
- margin-bottom: 1.2em;
- padding: 0.5em 0;
- border-top: 1px solid #ccc;
- margin-top: 0.5em;
-}
-
-div.related a:hover {
- color: #0095C4;
-}
-
-div.related:first-child {
- border-top: 0;
- border-bottom: 1px solid #ccc;
-}
-
-div.sphinxsidebar {
- background-color: #eeeeee;
- border-radius: 5px;
- line-height: 130%;
- font-size: smaller;
-}
-
-div.sphinxsidebar h3, div.sphinxsidebar h4 {
- margin-top: 1.5em;
-}
-
-div.sphinxsidebarwrapper > h3:first-child {
- margin-top: 0.2em;
-}
-
-div.sphinxsidebarwrapper > ul > li > ul > li {
- margin-bottom: 0.4em;
-}
-
-div.sphinxsidebar a:hover {
- color: #0095C4;
-}
-
-div.sphinxsidebar input {
- font-family: 'Lucida Grande',Arial,sans-serif;
- border: 1px solid #999999;
- font-size: smaller;
- border-radius: 3px;
-}
-
-div.sphinxsidebar input[type=text] {
- max-width: 150px;
-}
-
-div.body {
- padding: 0 0 0 1.2em;
-}
-
-div.body p {
- line-height: 140%;
-}
-
-div.body h1, div.body h2, div.body h3, div.body h4, div.body h5, div.body h6 {
- margin: 0;
- border: 0;
- padding: 0.3em 0;
-}
-
-div.body hr {
- border: 0;
- background-color: #ccc;
- height: 1px;
-}
-
-div.body pre {
- border-radius: 3px;
- border: 1px solid #ac9;
-}
-
-div.body div.admonition, div.body div.impl-detail {
- border-radius: 3px;
-}
-
-div.body div.impl-detail > p {
- margin: 0;
-}
-
-div.body div.seealso {
- border: 1px solid #dddd66;
-}
-
-div.body a {
- color: #00608f;
-}
-
-div.body a:visited {
- color: #30306f;
-}
-
-div.body a:hover {
- color: #00B0E4;
-}
-
-tt, pre {
- font-family: monospace, sans-serif;
- font-size: 96.5%;
-}
-
-div.body tt {
- border-radius: 3px;
-}
-
-div.body tt.descname {
- font-size: 120%;
-}
-
-div.body tt.xref, div.body a tt {
- font-weight: normal;
-}
-
-p.deprecated {
- border-radius: 3px;
-}
-
-table.docutils {
- border: 1px solid #ddd;
- min-width: 20%;
- border-radius: 3px;
- margin-top: 10px;
- margin-bottom: 10px;
-}
-
-table.docutils td, table.docutils th {
- border: 1px solid #ddd !important;
- border-radius: 3px;
-}
-
-table p, table li {
- text-align: left !important;
-}
-
-table.docutils th {
- background-color: #eee;
- padding: 0.3em 0.5em;
-}
-
-table.docutils td {
- background-color: white;
- padding: 0.3em 0.5em;
-}
-
-table.footnote, table.footnote td {
- border: 0 !important;
-}
-
-div.footer {
- line-height: 150%;
- margin-top: -2em;
- text-align: right;
- width: auto;
- margin-right: 10px;
-}
-
-div.footer a:hover {
- color: #0095C4;
-}
diff --git a/doc/_themes/pydoctheme/theme.conf b/doc/_themes/pydoctheme/theme.conf
deleted file mode 100644
index 0c43881..0000000
--- a/doc/_themes/pydoctheme/theme.conf
+++ /dev/null
@@ -1,23 +0,0 @@
-[theme]
-inherit = default
-stylesheet = pydoctheme.css
-pygments_style = sphinx
-
-[options]
-bodyfont = 'Lucida Grande', Arial, sans-serif
-headfont = 'Lucida Grande', Arial, sans-serif
-footerbgcolor = white
-footertextcolor = #555555
-relbarbgcolor = white
-relbartextcolor = #666666
-relbarlinkcolor = #444444
-sidebarbgcolor = white
-sidebartextcolor = #444444
-sidebarlinkcolor = #444444
-bgcolor = white
-textcolor = #222222
-linkcolor = #0090c0
-visitedlinkcolor = #00608f
-headtextcolor = #1a1a1a
-headbgcolor = white
-headlinkcolor = #aaaaaa
diff --git a/doc/source/_templates/autosummary/class.rst b/doc/source/_templates/autosummary/class.rst
index ed9acaa..cff0295 100644
--- a/doc/source/_templates/autosummary/class.rst
+++ b/doc/source/_templates/autosummary/class.rst
@@ -1,29 +1,32 @@
-{% extends "!autosummary/class.rst" %}
+{{ fullname }}
+{{ underline }}
-.. currentmodule:: freetypy
+.. currentmodule:: {{ module }}
-{% block methods %}
-{% if methods %}
- .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
- .. autosummary::
- :toctree:
- {% for item in all_methods %}
- {%- if not item.startswith('_') or item in ['__call__'] %}
- {{ name }}.{{ item }}
- {%- endif -%}
- {%- endfor %}
-{% endif %}
-{% endblock %}
+.. autoclass:: {{ objname }}
-{% block attributes %}
-{% if attributes %}
- .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
- .. autosummary::
- :toctree:
- {% for item in all_attributes %}
- {%- if not item.startswith('_') %}
- {{ name }}.{{ item }}
- {%- endif -%}
- {%- endfor %}
-{% endif %}
-{% endblock %}
+ {% block methods %}
+ .. automethod:: __init__
+
+ {% if methods %}
+ .. rubric:: Methods
+
+ .. autosummary::
+ :toctree: _generated
+ {% for item in methods %}
+ ~{{ name }}.{{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
+
+ {% block attributes %}
+ {% if attributes %}
+ .. rubric:: Attributes
+
+ .. autosummary::
+ :toctree: _generated
+ {% for item in attributes %}
+ ~{{ name }}.{{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 914194b..11d7e04 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -33,7 +33,7 @@
'sphinx.ext.intersphinx',
'sphinx.ext.mathjax',
'sphinx.ext.ifconfig',
- 'sphinxext.numpydoc']
+ 'sphinx.ext.napoleon']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -96,11 +96,14 @@
autosummary_generate = ['api.rst']
+autoclass_content = 'class'
+autodoc_default_flags = []
+
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
-html_theme = 'pydoctheme'
+html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@@ -108,7 +111,7 @@
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ["../_themes",]
+# html_theme_path = ["../_themes",]
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
diff --git a/doc/source/intro.rst b/doc/source/intro.rst
index cf6031f..6aa17bb 100644
--- a/doc/source/intro.rst
+++ b/doc/source/intro.rst
@@ -2,7 +2,7 @@ Introduction to freetypy
========================
Since freetypy closely follows freetype's native C API, the `freetype
-documentation <http://freetype.org/freetype2/documentation.html>`_
+documentation <http://freetype.org/freetype2/docs/documentation.html>`_
serves as a good introduction to freetypy as well.
Basic usage
diff --git a/doc/sphinxext/__init__.py b/doc/sphinxext/__init__.py
deleted file mode 100644
index ae9073b..0000000
--- a/doc/sphinxext/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-from numpydoc import setup
diff --git a/doc/sphinxext/docscrape.py b/doc/sphinxext/docscrape.py
deleted file mode 100644
index cedb53a..0000000
--- a/doc/sphinxext/docscrape.py
+++ /dev/null
@@ -1,505 +0,0 @@
-"""Extract reference documentation from the NumPy source tree.
-
-"""
-
-import inspect
-import textwrap
-import re
-import pydoc
-from StringIO import StringIO
-from warnings import warn
-
-class Reader(object):
- """A line-based string reader.
-
- """
- def __init__(self, data):
- """
- Parameters
- ----------
- data : str
- String with lines separated by '\n'.
-
- """
- if isinstance(data,list):
- self._str = data
- else:
- self._str = data.split('\n') # store string as list of lines
-
- self.reset()
-
- def __getitem__(self, n):
- return self._str[n]
-
- def reset(self):
- self._l = 0 # current line nr
-
- def read(self):
- if not self.eof():
- out = self[self._l]
- self._l += 1
- return out
- else:
- return ''
-
- def seek_next_non_empty_line(self):
- for l in self[self._l:]:
- if l.strip():
- break
- else:
- self._l += 1
-
- def eof(self):
- return self._l >= len(self._str)
-
- def read_to_condition(self, condition_func):
- start = self._l
- for line in self[start:]:
- if condition_func(line):
- return self[start:self._l]
- self._l += 1
- if self.eof():
- return self[start:self._l+1]
- return []
-
- def read_to_next_empty_line(self):
- self.seek_next_non_empty_line()
- def is_empty(line):
- return not line.strip()
- return self.read_to_condition(is_empty)
-
- def read_to_next_unindented_line(self):
- def is_unindented(line):
- return (line.strip() and (len(line.lstrip()) == len(line)))
- return self.read_to_condition(is_unindented)
-
- def peek(self,n=0):
- if self._l + n < len(self._str):
- return self[self._l + n]
- else:
- return ''
-
- def is_empty(self):
- return not ''.join(self._str).strip()
-
-
-class NumpyDocString(object):
- def __init__(self, docstring, config={}):
- docstring = textwrap.dedent(docstring).split('\n')
-
- self._doc = Reader(docstring)
- self._parsed_data = {
- 'Signature': '',
- 'Summary': [''],
- 'Extended Summary': [],
- 'Parameters': [],
- 'Returns': [],
- 'Raises': [],
- 'Warns': [],
- 'Other Parameters': [],
- 'Attributes': [],
- 'Methods': [],
- 'See Also': [],
- 'Notes': [],
- 'Warnings': [],
- 'References': '',
- 'Examples': '',
- 'index': {}
- }
-
- self._parse()
-
- def __getitem__(self,key):
- return self._parsed_data[key]
-
- def __setitem__(self,key,val):
- if not self._parsed_data.has_key(key):
- warn("Unknown section %s" % key)
- else:
- self._parsed_data[key] = val
-
- def _is_at_section(self):
- self._doc.seek_next_non_empty_line()
-
- if self._doc.eof():
- return False
-
- l1 = self._doc.peek().strip() # e.g. Parameters
-
- if l1.startswith('.. index::'):
- return True
-
- l2 = self._doc.peek(1).strip() # ---------- or ==========
- return l2.startswith('-'*len(l1)) or l2.startswith('='*len(l1))
-
- def _strip(self,doc):
- i = 0
- j = 0
- for i,line in enumerate(doc):
- if line.strip(): break
-
- for j,line in enumerate(doc[::-1]):
- if line.strip(): break
-
- return doc[i:len(doc)-j]
-
- def _read_to_next_section(self):
- section = self._doc.read_to_next_empty_line()
-
- while not self._is_at_section() and not self._doc.eof():
- if not self._doc.peek(-1).strip(): # previous line was empty
- section += ['']
-
- section += self._doc.read_to_next_empty_line()
-
- return section
-
- def _read_sections(self):
- while not self._doc.eof():
- data = self._read_to_next_section()
- name = data[0].strip()
-
- if name.startswith('..'): # index section
- yield name, data[1:]
- elif len(data) < 2:
- yield StopIteration
- else:
- yield name, self._strip(data[2:])
-
- def _parse_param_list(self,content):
- r = Reader(content)
- params = []
- while not r.eof():
- header = r.read().strip()
- if ' : ' in header:
- arg_name, arg_type = header.split(' : ')[:2]
- else:
- arg_name, arg_type = header, ''
-
- desc = r.read_to_next_unindented_line()
- desc = dedent_lines(desc)
-
- params.append((arg_name,arg_type,desc))
-
- return params
-
-
- _name_rgx = re.compile(r"^\s*(:(?P<role>\w+):`(?P<name>[a-zA-Z0-9_.-]+)`|"
- r" (?P<name2>[a-zA-Z0-9_.-]+))\s*", re.X)
- def _parse_see_also(self, content):
- """
- func_name : Descriptive text
- continued text
- another_func_name : Descriptive text
- func_name1, func_name2, :meth:`func_name`, func_name3
-
- """
- items = []
-
- def parse_item_name(text):
- """Match ':role:`name`' or 'name'"""
- m = self._name_rgx.match(text)
- if m:
- g = m.groups()
- if g[1] is None:
- return g[3], None
- else:
- return g[2], g[1]
- raise ValueError("%s is not a item name" % text)
-
- def push_item(name, rest):
- if not name:
- return
- name, role = parse_item_name(name)
- items.append((name, list(rest), role))
- del rest[:]
-
- current_func = None
- rest = []
-
- for line in content:
- if not line.strip(): continue
-
- m = self._name_rgx.match(line)
- if m and line[m.end():].strip().startswith(':'):
- push_item(current_func, rest)
- current_func, line = line[:m.end()], line[m.end():]
- rest = [line.split(':', 1)[1].strip()]
- if not rest[0]:
- rest = []
- elif not line.startswith(' '):
- push_item(current_func, rest)
- current_func = None
- if ',' in line:
- for func in line.split(','):
- if func.strip():
- push_item(func, [])
- elif line.strip():
- current_func = line
- elif current_func is not None:
- rest.append(line.strip())
- push_item(current_func, rest)
- return items
-
- def _parse_index(self, section, content):
- """
- .. index: default
- :refguide: something, else, and more
-
- """
- def strip_each_in(lst):
- return [s.strip() for s in lst]
-
- out = {}
- section = section.split('::')
- if len(section) > 1:
- out['default'] = strip_each_in(section[1].split(','))[0]
- for line in content:
- line = line.split(':')
- if len(line) > 2:
- out[line[1]] = strip_each_in(line[2].split(','))
- return out
-
- def _parse_summary(self):
- """Grab signature (if given) and summary"""
- if self._is_at_section():
- return
-
- summary = self._doc.read_to_next_empty_line()
- summary_str = " ".join([s.strip() for s in summary]).strip()
- if re.compile('^([\w., ]+=)?\s*[\w\.]+\(.*\)$').match(summary_str):
- self['Signature'] = summary_str
- if not self._is_at_section():
- self['Summary'] = self._doc.read_to_next_empty_line()
- else:
- self['Summary'] = summary
-
- if not self._is_at_section():
- self['Extended Summary'] = self._read_to_next_section()
-
- def _parse(self):
- self._doc.reset()
- self._parse_summary()
-
- for (section,content) in self._read_sections():
- if not section.startswith('..'):
- section = ' '.join([s.capitalize() for s in section.split(' ')])
- if section in ('Parameters', 'Returns', 'Raises', 'Warns',
- 'Other Parameters', 'Attributes', 'Methods'):
- self[section] = self._parse_param_list(content)
- elif section.startswith('.. index::'):
- self['index'] = self._parse_index(section, content)
- elif section == 'See Also':
- self['See Also'] = self._parse_see_also(content)
- else:
- self[section] = content
-
- # string conversion routines
-
- def _str_header(self, name, symbol='-'):
- return [name, len(name)*symbol]
-
- def _str_indent(self, doc, indent=4):
- out = []
- for line in doc:
- out += [' '*indent + line]
- return out
-
- def _str_signature(self):
- if self['Signature']:
- return [self['Signature'].replace('*','\*')] + ['']
- else:
- return ['']
-
- def _str_summary(self):
- if self['Summary']:
- return self['Summary'] + ['']
- else:
- return []
-
- def _str_extended_summary(self):
- if self['Extended Summary']:
- return self['Extended Summary'] + ['']
- else:
- return []
-
- def _str_param_list(self, name):
- out = []
- if self[name]:
- out += self._str_header(name)
- for param,param_type,desc in self[name]:
- out += ['%s : %s' % (param, param_type)]
- out += self._str_indent(desc)
- out += ['']
- return out
-
- def _str_section(self, name):
- out = []
- if self[name]:
- out += self._str_header(name)
- out += self[name]
- out += ['']
- return out
-
- def _str_see_also(self, func_role):
- if not self['See Also']: return []
- out = []
- out += self._str_header("See Also")
- last_had_desc = True
- for func, desc, role in self['See Also']:
- if role:
- link = ':%s:`%s`' % (role, func)
- elif func_role:
- link = ':%s:`%s`' % (func_role, func)
- else:
- link = "`%s`_" % func
- if desc or last_had_desc:
- out += ['']
- out += [link]
- else:
- out[-1] += ", %s" % link
- if desc:
- out += self._str_indent([' '.join(desc)])
- last_had_desc = True
- else:
- last_had_desc = False
- out += ['']
- return out
-
- def _str_index(self):
- idx = self['index']
- out = []
- out += ['.. index:: %s' % idx.get('default','')]
- for section, references in idx.iteritems():
- if section == 'default':
- continue
- out += [' :%s: %s' % (section, ', '.join(references))]
- return out
-
- def __str__(self, func_role=''):
- out = []
- out += self._str_signature()
- out += self._str_summary()
- out += self._str_extended_summary()
- for param_list in ('Parameters', 'Returns', 'Other Parameters',
- 'Raises', 'Warns'):
- out += self._str_param_list(param_list)
- out += self._str_section('Warnings')
- out += self._str_see_also(func_role)
- for s in ('Notes','References','Examples'):
- out += self._str_section(s)
- for param_list in ('Attributes', 'Methods'):
- out += self._str_param_list(param_list)
- out += self._str_index()
- return '\n'.join(out)
-
-
-def indent(str,indent=4):
- indent_str = ' '*indent
- if str is None:
- return indent_str
- lines = str.split('\n')
- return '\n'.join(indent_str + l for l in lines)
-
-def dedent_lines(lines):
- """Deindent a list of lines maximally"""
- return textwrap.dedent("\n".join(lines)).split("\n")
-
-def header(text, style='-'):
- return text + '\n' + style*len(text) + '\n'
-
-
-class FunctionDoc(NumpyDocString):
- def __init__(self, func, role='func', doc=None, config={}):
- self._f = func
- self._role = role # e.g. "func" or "meth"
-
- if doc is None:
- if func is None:
- raise ValueError("No function or docstring given")
- doc = inspect.getdoc(func) or ''
- NumpyDocString.__init__(self, doc)
-
- if not self['Signature'] and func is not None:
- func, func_name = self.get_func()
- try:
- # try to read signature
- argspec = inspect.getargspec(func)
- argspec = inspect.formatargspec(*argspec)
- argspec = argspec.replace('*','\*')
- signature = '%s%s' % (func_name, argspec)
- except TypeError, e:
- signature = '%s()' % func_name
- self['Signature'] = signature
-
- def get_func(self):
- func_name = getattr(self._f, '__name__', self.__class__.__name__)
- if inspect.isclass(self._f):
- func = getattr(self._f, '__call__', self._f.__init__)
- else:
- func = self._f
- return func, func_name
-
- def __str__(self):
- out = ''
-
- func, func_name = self.get_func()
- signature = self['Signature'].replace('*', '\*')
-
- roles = {'func': 'function',
- 'meth': 'method'}
-
- if self._role:
- if not roles.has_key(self._role):
- print "Warning: invalid role %s" % self._role
- out += '.. %s:: %s\n \n\n' % (roles.get(self._role,''),
- func_name)
-
- out += super(FunctionDoc, self).__str__(func_role=self._role)
- return out
-
-
-class ClassDoc(NumpyDocString):
-
- extra_public_methods = ['__call__']
-
- def __init__(self, cls, doc=None, modulename='', func_doc=FunctionDoc,
- config={}):
- if not inspect.isclass(cls) and cls is not None:
- raise ValueError("Expected a class or None, but got %r" % cls)
- self._cls = cls
-
- if modulename and not modulename.endswith('.'):
- modulename += '.'
- self._mod = modulename
-
- if doc is None:
- if cls is None:
- raise ValueError("No class or documentation string given")
- doc = pydoc.getdoc(cls)
-
- NumpyDocString.__init__(self, doc)
-
- if config.get('show_class_members', True):
- if not self['Methods']:
- self['Methods'] = [(name, '', '')
- for name in sorted(self.methods)]
- if not self['Attributes']:
- self['Attributes'] = [(name, '', '')
- for name in sorted(self.properties)]
-
- @property
- def methods(self):
- if self._cls is None:
- return []
- return [name for name,func in inspect.getmembers(self._cls)
- if ((not name.startswith('_')
- or name in self.extra_public_methods)
- and callable(func))]
-
- @property
- def properties(self):
- if self._cls is None:
- return []
- return [name for name,func in inspect.getmembers(self._cls)
- if not name.startswith('_') and not callable(func)]
diff --git a/doc/sphinxext/docscrape_sphinx.py b/doc/sphinxext/docscrape_sphinx.py
deleted file mode 100644
index e44e770..0000000
--- a/doc/sphinxext/docscrape_sphinx.py
+++ /dev/null
@@ -1,227 +0,0 @@
-import re, inspect, textwrap, pydoc
-import sphinx
-from docscrape import NumpyDocString, FunctionDoc, ClassDoc
-
-class SphinxDocString(NumpyDocString):
- def __init__(self, docstring, config={}):
- self.use_plots = config.get('use_plots', False)
- NumpyDocString.__init__(self, docstring, config=config)
-
- # string conversion routines
- def _str_header(self, name, symbol='`'):
- return ['.. rubric:: ' + name, '']
-
- def _str_field_list(self, name):
- return [':' + name + ':']
-
- def _str_indent(self, doc, indent=4):
- out = []
- for line in doc:
- out += [' '*indent + line]
- return out
-
- def _str_signature(self):
- return ['']
- if self['Signature']:
- return ['``%s``' % self['Signature']] + ['']
- else:
- return ['']
-
- def _str_summary(self):
- return self['Summary'] + ['']
-
- def _str_extended_summary(self):
- return self['Extended Summary'] + ['']
-
- def _str_param_list(self, name):
- out = []
- if self[name]:
- out += self._str_field_list(name)
- out += ['']
- for param,param_type,desc in self[name]:
- out += self._str_indent(['**%s** : %s' % (param.strip(),
- param_type)])
- out += ['']
- out += self._str_indent(desc,8)
- out += ['']
- return out
-
- @property
- def _obj(self):
- if hasattr(self, '_cls'):
- return self._cls
- elif hasattr(self, '_f'):
- return self._f
- return None
-
- def _str_member_list(self, name):
- """
- Generate a member listing, autosummary:: table where possible,
- and a table where not.
-
- """
- out = []
- if self[name]:
- out += ['.. rubric:: %s' % name, '']
- prefix = getattr(self, '_name', '')
-
- if prefix:
- prefix = '~%s.' % prefix
-
- autosum = []
- others = []
- for param, param_type, desc in self[name]:
- param = param.strip()
- if not self._obj or hasattr(self._obj, param):
- autosum += [" %s%s" % (prefix, param)]
- else:
- others.append((param, param_type, desc))
-
- if autosum:
- out += ['.. autosummary::', ' :toctree:', '']
- out += autosum
-
- if others:
- maxlen_0 = max([len(x[0]) for x in others])
- maxlen_1 = max([len(x[1]) for x in others])
- hdr = "="*maxlen_0 + " " + "="*maxlen_1 + " " + "="*10
- fmt = '%%%ds %%%ds ' % (maxlen_0, maxlen_1)
- n_indent = maxlen_0 + maxlen_1 + 4
- out += [hdr]
- for param, param_type, desc in others:
- out += [fmt % (param.strip(), param_type)]
- out += self._str_indent(desc, n_indent)
- out += [hdr]
- out += ['']
- return out
-
- def _str_section(self, name):
- out = []
- if self[name]:
- out += self._str_header(name)
- out += ['']
- content = textwrap.dedent("\n".join(self[name])).split("\n")
- out += content
- out += ['']
- return out
-
- def _str_see_also(self, func_role):
- out = []
- if self['See Also']:
- see_also = super(SphinxDocString, self)._str_see_also(func_role)
- out = ['.. seealso::', '']
- out += self._str_indent(see_also[2:])
- return out
-
- def _str_warnings(self):
- out = []
- if self['Warnings']:
- out = ['.. warning::', '']
- out += self._str_indent(self['Warnings'])
- return out
-
- def _str_index(self):
- idx = self['index']
- out = []
- if len(idx) == 0:
- return out
-
- out += ['.. index:: %s' % idx.get('default','')]
- for section, references in idx.iteritems():
- if section == 'default':
- continue
- elif section == 'refguide':
- out += [' single: %s' % (', '.join(references))]
- else:
- out += [' %s: %s' % (section, ','.join(references))]
- return out
-
- def _str_references(self):
- out = []
- if self['References']:
- out += self._str_header('References')
- if isinstance(self['References'], str):
- self['References'] = [self['References']]
- out.extend(self['References'])
- out += ['']
- # Latex collects all references to a separate bibliography,
- # so we need to insert links to it
- if sphinx.__version__ >= "0.6":
- out += ['.. only:: latex','']
- else:
- out += ['.. latexonly::','']
- items = []
- for line in self['References']:
- m = re.match(r'.. \[([a-z0-9._-]+)\]', line, re.I)
- if m:
- items.append(m.group(1))
- out += [' ' + ", ".join(["[%s]_" % item for item in items]), '']
- return out
-
- def _str_examples(self):
- examples_str = "\n".join(self['Examples'])
-
- if (self.use_plots and 'import matplotlib' in examples_str
- and 'plot::' not in examples_str):
- out = []
- out += self._str_header('Examples')
- out += ['.. plot::', '']
- out += self._str_indent(self['Examples'])
- out += ['']
- return out
- else:
- return self._str_section('Examples')
-
- def __str__(self, indent=0, func_role="obj"):
- out = []
- out += self._str_signature()
- out += self._str_index() + ['']
- out += self._str_summary()
- out += self._str_extended_summary()
- for param_list in ('Parameters', 'Returns', 'Other Parameters',
- 'Raises', 'Warns'):
- out += self._str_param_list(param_list)
- out += self._str_warnings()
- out += self._str_see_also(func_role)
- out += self._str_section('Notes')
- out += self._str_references()
- out += self._str_examples()
- for param_list in ('Attributes', 'Methods'):
- out += self._str_member_list(param_list)
- out = self._str_indent(out,indent)
- return '\n'.join(out)
-
-class SphinxFunctionDoc(SphinxDocString, FunctionDoc):
- def __init__(self, obj, doc=None, config={}):
- self.use_plots = config.get('use_plots', False)
- FunctionDoc.__init__(self, obj, doc=doc, config=config)
-
-class SphinxClassDoc(SphinxDocString, ClassDoc):
- def __init__(self, obj, doc=None, func_doc=None, config={}):
- self.use_plots = config.get('use_plots', False)
- ClassDoc.__init__(self, obj, doc=doc, func_doc=None, config=config)
-
-class SphinxObjDoc(SphinxDocString):
- def __init__(self, obj, doc=None, config={}):
- self._f = obj
- SphinxDocString.__init__(self, doc, config=config)
-
-def get_doc_object(obj, what=None, doc=None, config={}):
- if what is None:
- if inspect.isclass(obj):
- what = 'class'
- elif inspect.ismodule(obj):
- what = 'module'
- elif callable(obj):
- what = 'function'
- else:
- what = 'object'
- if what == 'class':
- return SphinxClassDoc(obj, func_doc=SphinxFunctionDoc, doc=doc,
- config=config)
- elif what in ('function', 'method'):
- return SphinxFunctionDoc(obj, doc=doc, config=config)
- else:
- if doc is None:
- doc = pydoc.getdoc(obj)
- return SphinxObjDoc(obj, doc, config=config)
diff --git a/doc/sphinxext/numpydoc.py b/doc/sphinxext/numpydoc.py
deleted file mode 100644
index 7679352..0000000
--- a/doc/sphinxext/numpydoc.py
+++ /dev/null
@@ -1,169 +0,0 @@
-"""
-========
-numpydoc
-========
-
-Sphinx extension that handles docstrings in the Numpy standard format. [1]
-
-It will:
-
-- Convert Parameters etc. sections to field lists.
-- Convert See Also section to a See also entry.
-- Renumber references.
-- Extract the signature from the docstring, if it can't be determined otherwise.
-
-.. [1] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
-
-"""
-
-import sphinx
-
-if sphinx.__version__ < '1.0.1':
- raise RuntimeError("Sphinx 1.0.1 or newer is required")
-
-import os, re, pydoc
-from docscrape_sphinx import get_doc_object, SphinxDocString
-from sphinx.util.compat import Directive
-import inspect
-
-def mangle_docstrings(app, what, name, obj, options, lines,
- reference_offset=[0]):
-
- cfg = dict(use_plots=app.config.numpydoc_use_plots,
- show_class_members=app.config.numpydoc_show_class_members)
-
- if what == 'module':
- # Strip top title
- title_re = re.compile(ur'^\s*[#*=]{4,}\n[a-z0-9 -]+\n[#*=]{4,}\s*',
- re.I|re.S)
- lines[:] = title_re.sub(u'', u"\n".join(lines)).split(u"\n")
- else:
- doc = get_doc_object(obj, what, u"\n".join(lines), config=cfg)
- lines[:] = unicode(doc).split(u"\n")
-
- if app.config.numpydoc_edit_link and hasattr(obj, '__name__') and \
- obj.__name__:
- if hasattr(obj, '__module__'):
- v = dict(full_name=u"%s.%s" % (obj.__module__, obj.__name__))
- else:
- v = dict(full_name=obj.__name__)
- lines += [u'', u'.. htmlonly::', '']
- lines += [u' %s' % x for x in
- (app.config.numpydoc_edit_link % v).split("\n")]
-
- # replace reference numbers so that there are no duplicates
- references = []
- for line in lines:
- line = line.strip()
- m = re.match(ur'^.. \[([a-z0-9_.-])\]', line, re.I)
- if m:
- references.append(m.group(1))
-
- # start renaming from the longest string, to avoid overwriting parts
- references.sort(key=lambda x: -len(x))
- if references:
- for i, line in enumerate(lines):
- for r in references:
- if re.match(ur'^\d+$', r):
- new_r = u"R%d" % (reference_offset[0] + int(r))
- else:
- new_r = u"%s%d" % (r, reference_offset[0])
- lines[i] = lines[i].replace(u'[%s]_' % r,
- u'[%s]_' % new_r)
- lines[i] = lines[i].replace(u'.. [%s]' % r,
- u'.. [%s]' % new_r)
-
- reference_offset[0] += len(references)
-
-def mangle_signature(app, what, name, obj, options, sig, retann):
- # Do not try to inspect classes that don't define `__init__`
- if (inspect.isclass(obj) and
- (not hasattr(obj, '__init__') or
- 'initializes x; see ' in pydoc.getdoc(obj.__init__))):
- return '', ''
-
- if not (callable(obj) or hasattr(obj, '__argspec_is_invalid_')): return
- if not hasattr(obj, '__doc__'): return
-
- doc = SphinxDocString(pydoc.getdoc(obj))
- if doc['Signature']:
- sig = re.sub(u"^[^(]*", u"", doc['Signature'])
- return sig, u''
-
-def setup(app, get_doc_object_=get_doc_object):
- global get_doc_object
- get_doc_object = get_doc_object_
-
- app.connect('autodoc-process-docstring', mangle_docstrings)
- app.connect('autodoc-process-signature', mangle_signature)
- app.add_config_value('numpydoc_edit_link', None, False)
- app.add_config_value('numpydoc_use_plots', None, False)
- app.add_config_value('numpydoc_show_class_members', True, True)
-
- # Extra mangling domains
- app.add_domain(NumpyPythonDomain)
- app.add_domain(NumpyCDomain)
-
-#------------------------------------------------------------------------------
-# Docstring-mangling domains
-#------------------------------------------------------------------------------
-
-from docutils.statemachine import ViewList
-from sphinx.domains.c import CDomain
-from sphinx.domains.python import PythonDomain
-
-class ManglingDomainBase(object):
- directive_mangling_map = {}
-
- def __init__(self, *a, **kw):
- super(ManglingDomainBase, self).__init__(*a, **kw)
- self.wrap_mangling_directives()
-
- def wrap_mangling_directives(self):
- for name, objtype in self.directive_mangling_map.items():
- self.directives[name] = wrap_mangling_directive(
- self.directives[name], objtype)
-
-class NumpyPythonDomain(ManglingDomainBase, PythonDomain):
- name = 'np'
- directive_mangling_map = {
- 'function': 'function',
- 'class': 'class',
- 'exception': 'class',
- 'method': 'function',
- 'classmethod': 'function',
- 'staticmethod': 'function',
- 'attribute': 'attribute',
- }
-
-class NumpyCDomain(ManglingDomainBase, CDomain):
- name = 'np-c'
- directive_mangling_map = {
- 'function': 'function',
- 'member': 'attribute',
- 'macro': 'function',
- 'type': 'class',
- 'var': 'object',
- }
-
-def wrap_mangling_directive(base_directive, objtype):
- class directive(base_directive):
- def run(self):
- env = self.state.document.settings.env
-
- name = None
- if self.arguments:
- m = re.match(r'^(.*\s+)?(.*?)(\(.*)?', self.arguments[0])
- name = m.group(2).strip()
-
- if not name:
- name = self.arguments[0]
-
- lines = list(self.content)
- mangle_docstrings(env.app, objtype, name, None, None, lines)
- self.content = ViewList(lines, self.content.parent)
-
- return base_directive.run(self)
-
- return directive
-
diff --git a/docstrings/face.py b/docstrings/face.py
index c794fcb..93b0895 100644
--- a/docstrings/face.py
+++ b/docstrings/face.py
@@ -645,8 +645,8 @@
matrix : 2x2 sequence of floats, optional
A matrix of the form::
- [[xx, xy]
- [yx, yy]]
+ . [[xx, xy]
+ . [yx, yy]]
delta : 2-sequence of floats, optional
diff --git a/docstrings/outline.py b/docstrings/outline.py
index fff7533..d9f1ecd 100644
--- a/docstrings/outline.py
+++ b/docstrings/outline.py
@@ -306,8 +306,8 @@ def cubic_to(self, a, b, c):
matrix : 2x2 sequence of floats, optional
A matrix of the form::
- [[xx, xy]
- [yx, yy]]
+ . [[xx, xy]
+ . [yx, yy]]
"""
Outline_translate = """
From 907cd60c195e33b3da25d4df63be204bbe35948c Mon Sep 17 00:00:00 2001
From: Michael Droettboom <mdboom@gmail.com>
Date: Thu, 29 Oct 2015 15:20:57 -0400
Subject: [PATCH 2/2] Improve summary lines in docs
---
doc/source/_templates/autosummary/class.rst | 4 +-
docstrings/bitmap.py | 12 +-
docstrings/charmap.py | 4 +-
docstrings/face.py | 125 +++++++++++---------
docstrings/glyph.py | 37 +++---
docstrings/layout.py | 12 +-
docstrings/outline.py | 19 +--
docstrings/size_metrics.py | 18 ++-
lib/freetypy/util.py | 8 +-
9 files changed, 130 insertions(+), 109 deletions(-)
diff --git a/doc/source/_templates/autosummary/class.rst b/doc/source/_templates/autosummary/class.rst
index cff0295..e16614e 100644
--- a/doc/source/_templates/autosummary/class.rst
+++ b/doc/source/_templates/autosummary/class.rst
@@ -12,7 +12,7 @@
.. rubric:: Methods
.. autosummary::
- :toctree: _generated
+ :toctree: .
{% for item in methods %}
~{{ name }}.{{ item }}
{%- endfor %}
@@ -24,7 +24,7 @@
.. rubric:: Attributes
.. autosummary::
- :toctree: _generated
+ :toctree: .
{% for item in attributes %}
~{{ name }}.{{ item }}
{%- endfor %}
diff --git a/docstrings/bitmap.py b/docstrings/bitmap.py
index fbbc051..f9d253f 100644
--- a/docstrings/bitmap.py
+++ b/docstrings/bitmap.py
@@ -75,11 +75,13 @@
"""
Bitmap_pitch = """
-The pitch's absolute value is the number of bytes taken by one bitmap
-row, including padding. However, the pitch is positive when the bitmap
-has a ‘down’ flow, and negative when it has an ‘up’ flow. In all
-cases, the pitch is an offset to add to a bitmap pointer in order to
-go down one row.
+The number of bytes taken by one bitmap row.
+
+Includes padding.
+
+The pitch is positive when the bitmap has a ‘down’ flow, and negative
+when it has an ‘up’ flow. In all cases, the pitch is an offset to add
+to a bitmap pointer in order to go down one row.
Note that ‘padding’ means the alignment of a bitmap to a byte border,
and FreeType functions normally align to the smallest possible integer
diff --git a/docstrings/charmap.py b/docstrings/charmap.py
index 1a48cd4..0f2cc8b 100644
--- a/docstrings/charmap.py
+++ b/docstrings/charmap.py
@@ -67,7 +67,7 @@
"""
CharMap_get_format = """
-Return TrueType/sfnt specific cmap format.
+Get the TrueType/sfnt specific cmap format.
Returns
-------
@@ -77,7 +77,7 @@
"""
CharMap_get_language_id = """
-Return TrueType/sfnt specific cmap language ID.
+Get the TrueType/sfnt specific cmap language ID.
It will be one of the constants in `TT_MAC_LANGID` or `TT_MS_LANGID`.
diff --git a/docstrings/face.py b/docstrings/face.py
index 93b0895..6fac4b5 100644
--- a/docstrings/face.py
+++ b/docstrings/face.py
@@ -85,11 +85,11 @@
"""
Face_charmap = """
-The current active `CharMap` for this face.
+The currently active `CharMap`.
"""
Face_charmaps = """
-A list of `CharMap` objects in the face.
+A list of `CharMap` objects.
"""
Face_descender = """
@@ -119,12 +119,13 @@
"""
Face_filename = """
-|freetypy| The argument used to initialize the font. Is usually a
-filename, but not always.
+|freetypy| The argument used to initialize the font.
+
+It is usually a filename, but may be a file object.
"""
Face_get_char_index_unicode = """
-|freetypy| Return the glyph index of a given Unicode character.
+|freetypy| Get the glyph index of a given Unicode character.
Unlike `get_char_index`, if the selected `CharMap` is not Unicode, the
given unicode character will first be encoded to the correct character
@@ -140,22 +141,23 @@
Returns
-------
glyph_index : int
- The glyph index. 0 means ‘undefined character code’.
+ The glyph index. 0 means ‘undefined char code’.
"""
Face_get_char_index = """
-Return the glyph index of a given character code. This function uses a
-charmap object to do the mapping.
+Get the glyph index of a given char code.
+
+This function uses a charmap object to do the mapping.
Parameters
----------
charcode : int
- The character code.
+ The char code.
Returns
-------
glyph_index : int
- The glyph index. 0 means ‘undefined character code’.
+ The glyph index. 0 means ‘undefined char code’.
Notes
-----
@@ -172,14 +174,15 @@
"""
Face_get_char_name = """
-|freetypy| Returns the glyph name of the given unicode code point.
+|freetypy| Get the glyph name of the given unicode code point.
+
Unlike `get_glyph_name`, this function will always return something,
even if the font contains no glyph names.
Parameters
----------
charcode : int
- The character code.
+ The char code.
Returns
-------
@@ -188,13 +191,13 @@
"""
Face_get_char_variant_index = """
-Return the glyph index of a given character code as modified by the
-variation selector.
+Get the glyph id of a char code as modified by the variant
+selector.
Parameters
----------
charcode : int
- The character code point in Unicode.
+ The char code point in Unicode.
variantSelector : int
The Unicode code point of the variation selector.
@@ -202,7 +205,7 @@
Returns
-------
glyph_index : int
- The glyph index. 0 means either ‘undefined character code’, or
+ The glyph index. 0 means either ‘undefined char code’, or
‘undefined selector code’, or ‘no variation selector cmap
subtable’, or ‘current CharMap is not Unicode’.
@@ -219,16 +222,16 @@
"""
Face_get_chars = """
-Returns an iterator over all of the character codes in the current
-charmap.
+Iterate over all of the char codes in the current charmap.
-Each result of the iterator is a tuple of the form (`charcode`,
-`glyph_index`).
+Each result of the iterator is a tuple of the form ``(charcode,
+glyph_index)``.
"""
Face_get_fstype_flags = """
-Return the `FSTYPE` flags for a font, which indicate the licensing for
-embedding and subsetting a font.
+Get the `FSTYPE` flags for a font.
+
+These indicate the licensing for embedding and subsetting a font.
Returns
-------
@@ -237,8 +240,10 @@
"""
Face_get_glyph_name = """
-Retrieve the ASCII name of the given glyph in a face. This only works
-for those faces where `has_ps_glyph_names` returns `True`.
+Get the ASCII name of the given glyph in a face.
+
+This only works for those faces where `has_ps_glyph_names` returns
+`True`.
Parameters
----------
@@ -260,7 +265,7 @@
"""
Face_get_kerning = """
-Return the kerning vector between two glyphs of a same face.
+Get the kerning vector between two glyphs of a same face.
Parameters
----------
@@ -287,8 +292,9 @@
"""
Face_get_name_index = """
-Return the glyph index of a given glyph name. This function uses
-driver specific objects to do the translation.
+Get the glyph index of a given glyph name.
+
+This function uses driver specific objects to do the translation.
Parameters
----------
@@ -298,17 +304,17 @@
Returns
-------
glyph_index : int
- The glyph index. 0 means ‘undefined character code’.
+ The glyph index. 0 means ‘undefined char code’.
"""
Face_get_postscript_name = """
-Retrieve the ASCII PostScript name of a given face, if available.
+Get the ASCII PostScript name of a given face, if available.
This only works with PostScript and TrueType fonts.
"""
Face_get_track_kerning = """
-Return the track kerning for a given face object at a given size.
+Get the track kerning for a given face object at a given size.
Parameters
----------
@@ -335,31 +341,31 @@
"""
Face_tt_header = """
-The TrueType header (`TT_Header`) from the face.
+The TrueType header (`TT_Header`).
"""
Face_tt_horiheader = """
-The TrueType horizontal header (`TT_HoriHeader`) from the face.
+The TrueType horizontal header (`TT_HoriHeader`).
"""
Face_tt_os2 = """
-The OS/2 TrueType header (`TT_OS2`) from the face.
+The OS/2 TrueType header (`TT_OS2`).
"""
Face_tt_pclt = """
-The PCLT header (`TT_Pclt`) from the face.
+The PCLT header (`TT_Pclt`).
"""
Face_tt_postscript = """
-The Postscript header (`TT_Postscript`) from the face.
+The Postscript header (`TT_Postscript`).
"""
Face_tt_vertheader = """
-The TrueType vertical header (`TT_VertHeader`) from the face.
+The TrueType vertical header (`TT_VertHeader`).
"""
Face_glyph = """
-The face's associated glyph slot.
+The face's currently loaded glyph slot.
"""
Face_has_ps_glyph_names = """
@@ -370,20 +376,21 @@
"""
Face_height = """
-This value is the vertical distance between two consecutive baselines,
-expressed in font units. It is always positive. Only relevant for
-scalable formats.
+The vertical distance between two consecutive baselines, expressed in
+font units.
+
+It is always positive. Only relevant for scalable formats.
If you want the global glyph height, use `ascender` - `descender`.
"""
Face_load_char = """
-Load a single glyph, according to its character code.
+Load a single glyph, according to its char code.
Parameters
----------
char_code : int
- The glyph's character code, according to the current charmap used
+ The glyph's char code, according to the current charmap used
in the face.
load_flags : int, optional
@@ -471,7 +478,7 @@
Note that the auto-hinter needs a valid Unicode cmap (either a native
one or synthesized by FreeType) for producing correct results. If a
font provides an incorrect mapping (for example, assigning the
-character code U+005A, LATIN CAPITAL LETTER Z, to a glyph depicting a
+char code U+005A, LATIN CAPITAL LETTER Z, to a glyph depicting a
mathematical integral sign), the auto-hinter might produce useless
results.
@@ -597,7 +604,7 @@
"""
Face_set_char_size = """
-Request a nominal font size (in points).
+Set the nominal font size (in points).
Parameters
----------
@@ -625,7 +632,7 @@
"""
Face_set_charmap = """
-Select a charmap for character code to glyph index mapping.
+Select a charmap for char code to glyph index mapping.
Parameters
----------
@@ -638,7 +645,7 @@
"""
Face_set_transform = """
-Set the transformation that is applied to glyph images.
+Set the transformation applied to glyph images.
Parameters
----------
@@ -666,7 +673,7 @@
"""
Face_size = """
-The current active size for this face.
+The currently active size.
"""
Face_style_flags = """
@@ -684,18 +691,20 @@
"""
Face_underline_position = """
-The position, in font units, of the underline line for this face. It
-is the center of the underlining stem. Only relevant for scalable
+The position of the underline line, in font units.
+
+It is the center of the underlining stem. Only relevant for scalable
formats.
"""
Face_underline_thickness = """
-The thickness, in font units, of the underline for this face. Only
-relevant for scalable formats.
+The thickness of the underline, in font units.
+
+Only relevant for scalable formats.
"""
Face_units_per_em = """
-The number of font units per EM square for this face.
+The number of font units per EM square.
This is typically 2048 for TrueType fonts, and 1000 for Type 1
fonts. Only relevant for scalable formats.
@@ -992,37 +1001,37 @@
"""
Face_has_horizontal = """
-`True` whenever a face object contains horizontal metrics.
+Horizontal metrics are present.
This is `True` for all font formats though.
"""
Face_has_vertical = """
-`True` whenever a face object contains real vertical metrics.
+Vertical metrics are present.
`False` when the face contains only synthesized vertical metrics.
"""
Face_has_kerning = """
-`True` whenever a face object contains kerning data.
+Kerning data is present.
The kerning data can be accessed with `Face.get_kerning`.
"""
Face_is_scalable = """
-`True` whenever a face object contains a scalable font face.
+Is a scalable `Face`.
This includes TrueType, Type 1, Type 42, CID, OpenType/CFF, and PFR
font formats.
"""
Face_is_sfnt = """
-`True` whenever font is based on the SFNT storage scheme.
+Based on the SFNT storage scheme.
This usually means: TrueType fonts, OpenType fonts, as well as
SFNT-based embedded bitmap fonts.
"""
Face_is_fixed_width = """
-`True` whenever a font face contains fixed-width (or ‘monospace’) glyphs.
+Contains fixed-width (or ‘monospace’) glyphs.
"""
diff --git a/docstrings/glyph.py b/docstrings/glyph.py
index b1b2023..87aaa08 100644
--- a/docstrings/glyph.py
+++ b/docstrings/glyph.py
@@ -59,15 +59,15 @@
"""
Glyph_bitmap_left = """
-This is the bitmap's left bearing expressed in integer pixels. Of
-course, this is only valid if the format is `GLYPH_FORMAT.BITMAP`.
+The bitmap's left bearing expressed in integer pixels. Of course, this
+is only valid if the format is `GLYPH_FORMAT.BITMAP`.
"""
Glyph_bitmap_top = """
-This is the bitmap's top bearing expressed in integer pixels. Remember
-that this is the distance from the baseline to the top-most glyph
-scanline, upwards y coordinates being positive. Of course, this is
-only valid if the format is `GLYPH_FORMAT.BITMAP`.
+The bitmap's top bearing expressed in integer pixels. Remember that
+this is the distance from the baseline to the top-most glyph scanline,
+upwards *y* coordinates being positive. Of course, this is only valid
+if the format is `GLYPH_FORMAT.BITMAP`.
"""
Glyph_face = """
@@ -75,19 +75,20 @@
"""
Glyph_format = """
-This field indicates the format of the image contained in the glyph
-slot. Typically `GLYPH_FORMAT.BITMAP`, `GLYPH_FORMAT.OUTLINE`, or
+The format of the image in the glyph slot. Typically
+`GLYPH_FORMAT.BITMAP`, `GLYPH_FORMAT.OUTLINE`, or
`GLYPH_FORMAT.COMPOSITE`, but others are possible.
See `GLYPH_FORMAT` for the set of available formats.
"""
Glyph_get_cbox = """
-Return a glyph's ‘control box’. The control box encloses all the
-outline's points, including Bézier control points. Though it coincides
-with the exact bounding box for most glyphs, it can be slightly larger
-in some situations (like when rotating an outline which contains
-Bézier outside arcs).
+Get the glyph's ‘control box’.
+
+The control box encloses all the outline's points, including Bézier
+control points. Though it coincides with the exact bounding box for
+most glyphs, it can be slightly larger in some situations (like when
+rotating an outline which contains Bézier outside arcs).
Computing the control box is very fast, while getting the bounding box
can take much more time as it needs to walk over all segments and arcs
@@ -157,8 +158,9 @@
"""
Glyph_lsb_delta = """
-The difference between hinted and unhinted left side bearing while
-autohinting is active. Zero otherwise.
+The difference between hinted and unhinted left side bearing.
+
+Valid when autohinting is active. Zero otherwise.
"""
Glyph_metrics = """
@@ -206,8 +208,9 @@
"""
Glyph_rsb_delta = """
-The difference between hinted and unhinted right side bearing while
-autohinting is active. Zero otherwise.
+The difference between hinted and unhinted right side bearing
+
+Valid when autohinting is active. Zero otherwise.
"""
Glyph_subglyphs = """
diff --git a/docstrings/layout.py b/docstrings/layout.py
index dd90c19..5931e22 100644
--- a/docstrings/layout.py
+++ b/docstrings/layout.py
@@ -50,20 +50,20 @@
"""
Layout_ink_bbox = """
-Get the tight bounding box (`BBox`) of the physical characters in the
+The tight bounding box (`BBox`) of the physical characters in the
layout. The origin is at (0, 0). The result is in pixels.
"""
Layout_layout_bbox = """
-Get the logical bounding box (`BBox`) of the layout. This should be
-used to manage the layout of the text against other text. The result
-is in pixels.
+The logical bounding box (`BBox`) of the layout. This should be used
+to manage the layout of the text against other text. The result is in
+pixels.
"""
Layout_glyph_indices = """
-Get the glyph indices of each glyph in the layout.
+The glyph indices of each glyph in the layout.
"""
Layout_points = """
-Get the (x, y) location of each glyph in the layout.
+The (x, y) location of each glyph in the layout.
"""
diff --git a/docstrings/outline.py b/docstrings/outline.py
index d9f1ecd..771730e 100644
--- a/docstrings/outline.py
+++ b/docstrings/outline.py
@@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
-# Copyright (c) 2015, Michael Droettboom All rights reserved.
+# Copyright (c) 2013, Michael Droettboom All rights reserved.
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
@@ -193,9 +193,10 @@ def cubic_to(self, a, b, c):
"""
Outline_embolden_xy = """
-Embolden an outline. The new outline will be `xstrength` pixels wider
-and `ystrength` pixels higher. Otherwise, it is similar to
-`Outline.embolden`, which uses the same strength in both directions.
+Embolden an outline, with differing *x* and *y* amounts. The new
+outline will be `xstrength` pixels wider and `ystrength` pixels
+higher. Otherwise, it is similar to `Outline.embolden`, which uses the
+same strength in both directions.
Parameters
----------
@@ -228,11 +229,11 @@ def cubic_to(self, a, b, c):
"""
Outline_get_cbox = """
-Return an outline's ‘control box’. The control box encloses all the
-outline's points, including Bézier control points. Though it coincides
-with the exact bounding box for most glyphs, it can be slightly larger
-in some situations (like when rotating an outline which contains
-Bézier outside arcs).
+Get the control box. The control box encloses all the outline's
+points, including Bézier control points. Though it coincides with the
+exact bounding box for most glyphs, it can be slightly larger in some
+situations (like when rotating an outline which contains Bézier
+outside arcs).
Computing the control box is very fast, while getting the bounding box
can take much more time as it needs to walk over all segments and arcs
diff --git a/docstrings/size_metrics.py b/docstrings/size_metrics.py
index 524ddf1..c9a2058 100644
--- a/docstrings/size_metrics.py
+++ b/docstrings/size_metrics.py
@@ -75,9 +75,12 @@
"""
Size_Metrics_x_scale = """
-A fractional scaling value used to convert horizontal metrics from
-font units to 26.6 fractional pixels. Only relevant for scalable font
-formats.
+A fractional scaling value.
+
+Used to convert horizontal metrics from font units to 26.6 fractional
+pixels.
+
+Only relevant for scalable font formats.
"""
Size_Metrics_y_ppem = """
@@ -87,7 +90,10 @@
"""
Size_Metrics_y_scale = """
-A fractional scaling value used to convert horizontal metrics from
-font units to 26.6 fractional pixels. Only relevant for scalable font
-formats.
+A fractional scaling value.
+
+Used to convert horizontal metrics from font units to 26.6 fractional
+pixels.
+
+Only relevant for scalable font formats.
"""
diff --git a/lib/freetypy/util.py b/lib/freetypy/util.py
index 51c9b88..6a88627 100644
--- a/lib/freetypy/util.py
+++ b/lib/freetypy/util.py
@@ -43,16 +43,16 @@
def vera_path():
"""
- Returns the path to the copy of Bitstream Vera Sans that ships
- with freetypy for testing purposes.
+ The path to the copy of Bitstream Vera Sans that ships with
+ freetypy for testing purposes.
"""
return os.path.join(os.path.dirname(__file__), 'data', 'Vera.ttf')
def bitmap_to_ascii(a):
"""
- Converts a single glyph to a string with an ASCII drawing of that
- glyph.
+ Converts a single `Glyph` to a string with an ASCII drawing of
+ that glyph.
"""
shades = ' .+*#'