Skip to content

DOC: Making doc/source/conf.py pass PEP-8, and added to lint #19839

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 22, 2018
Merged

DOC: Making doc/source/conf.py pass PEP-8, and added to lint #19839

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
479091e
DOC: Making doc/source/conf.py pass PEP-8, and added to lint
datapythonista Feb 22, 2018
2b3adf5
edit
jorisvandenbossche Feb 22, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions ci/lint.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,12 +37,12 @@ if [ "$LINT" ]; then
fi
echo "Linting scripts/*.py DONE"

echo "Linting doc script"
flake8 doc/make.py
echo "Linting doc scripts"
flake8 doc/make.py doc/source/conf.py
if [ $? -ne "0" ]; then
RET=1
fi
echo "Linting doc script DONE"
echo "Linting doc scripts DONE"

echo "Linting *.pyx"
flake8 pandas --filename=*.pyx --select=E501,E302,E203,E111,E114,E221,E303,E128,E231,E126,E265,E305,E301,E127,E261,E271,E129,W291,E222,E241,E123,F403
Expand Down
66 changes: 35 additions & 31 deletions doc/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@
#
# pandas documentation build configuration file, created by
#
# This file is execfile()d with the current directory set to its containing dir.
# This file is execfile()d with the current directory set to its containing
# dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
Expand Down Expand Up @@ -49,8 +50,9 @@

# -- General configuration -----------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. sphinxext.
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
# sphinxext.

extensions = ['sphinx.ext.autodoc',
'sphinx.ext.autosummary',
Expand All @@ -60,7 +62,8 @@
'numpydoc',
'ipython_sphinxext.ipython_directive',
'ipython_sphinxext.ipython_console_highlighting',
'IPython.sphinxext.ipython_console_highlighting', # lowercase didn't work
# lowercase didn't work
'IPython.sphinxext.ipython_console_highlighting',
'sphinx.ext.intersphinx',
'sphinx.ext.coverage',
'sphinx.ext.mathjax',
Expand Down Expand Up @@ -95,22 +98,24 @@
files_to_delete.append(f)

if files_to_delete:
print("I'm about to DELETE the following:\n%s\n" % list(sorted(files_to_delete)))
sys.stdout.write("WARNING: I'd like to delete those to speed up processing (yes/no)? ")
print("I'm about to DELETE the following:\n{}\n".format(
list(sorted(files_to_delete))))
sys.stdout.write("WARNING: I'd like to delete those "
"to speed up processing (yes/no)? ")
if PY3:
answer = input()
else:
answer = raw_input()

if answer.lower().strip() in ('y','yes'):
if answer.lower().strip() in ('y', 'yes'):
for f in files_to_delete:
f = os.path.join(os.path.join(os.path.dirname(__file__),f))
f= os.path.abspath(f)
f = os.path.join(os.path.join(os.path.dirname(__file__), f))
f = os.path.abspath(f)
try:
print("Deleting %s" % f)
print("Deleting {}".format(f))
os.unlink(f)
except:
print("Error deleting %s" % f)
print("Error deleting {}".format(f))
pass

# Add any paths that contain templates here, relative to this directory.
Expand All @@ -137,7 +142,7 @@
import pandas

# version = '%s r%s' % (pandas.__version__, svn_version())
version = '%s' % (pandas.__version__)
version = str(pandas.__version__)

# The full version, including alpha/beta/rc tags.
release = version
Expand All @@ -159,8 +164,8 @@
# for source files.
exclude_trees = []

# The reST default role (used for this markup: `text`) to use for all documents.
# default_role = None
# The reST default role (used for this markup: `text`) to use for all
# documents. default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
Expand Down Expand Up @@ -334,8 +339,8 @@
# The font size ('10pt', '11pt' or '12pt').
# latex_font_size = '10pt'

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
# Grouping the document tree into LaTeX files. List of tuples (source start
# file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'pandas.tex',
u('pandas: powerful Python data analysis toolkit'),
Expand Down Expand Up @@ -392,23 +397,24 @@
# wherever the docs are built. The docs' target is the browser, not
# the console, so this is fine.
'pd.options.display.encoding="utf8"'
]
]


# Add custom Documenter to handle attributes/methods of an AccessorProperty
# eg pandas.Series.str and pandas.Series.dt (see GH9322)

import sphinx
from sphinx.util import rpartition
from sphinx.ext.autodoc import Documenter, MethodDocumenter, AttributeDocumenter
from sphinx.ext.autodoc import (Documenter,
MethodDocumenter,
AttributeDocumenter)
from sphinx.ext.autosummary import Autosummary


class AccessorDocumenter(MethodDocumenter):
"""
Specialized Documenter subclass for accessors.
"""

objtype = 'accessor'
directivetype = 'method'

Expand All @@ -426,7 +432,6 @@ class AccessorLevelDocumenter(Documenter):
Specialized Documenter subclass for objects on accessor level (methods,
attributes).
"""

# This is the simple straightforward version
# modname is None, base the last elements (eg 'hour')
# and path the part before (eg 'Series.dt')
Expand All @@ -436,7 +441,6 @@ class AccessorLevelDocumenter(Documenter):
# mod_cls = mod_cls.split('.')
#
# return modname, mod_cls + [base]

def resolve_name(self, modname, parents, path, base):
if modname is None:
if path:
Expand Down Expand Up @@ -471,16 +475,17 @@ def resolve_name(self, modname, parents, path, base):
return modname, parents + [base]


class AccessorAttributeDocumenter(AccessorLevelDocumenter, AttributeDocumenter):

class AccessorAttributeDocumenter(AccessorLevelDocumenter,
AttributeDocumenter):
objtype = 'accessorattribute'
directivetype = 'attribute'

# lower than AttributeDocumenter so this is not chosen for normal attributes
# lower than AttributeDocumenter so this is not chosen for normal
# attributes
priority = 0.6

class AccessorMethodDocumenter(AccessorLevelDocumenter, MethodDocumenter):

class AccessorMethodDocumenter(AccessorLevelDocumenter, MethodDocumenter):
objtype = 'accessormethod'
directivetype = 'method'

Expand Down Expand Up @@ -508,7 +513,6 @@ class PandasAutosummary(Autosummary):
This alternative autosummary class lets us override the table summary for
Series.plot and DataFrame.plot in the API docs.
"""

def _replace_pandas_items(self, display_name, sig, summary, real_name):
# this a hack: ideally we should extract the signature from the
# .__call__ method instead of hard coding this
Expand Down Expand Up @@ -561,18 +565,18 @@ def linkcode_resolve(domain, info):
lineno = None

if lineno:
linespec = "#L%d-L%d" % (lineno, lineno + len(source) - 1)
linespec = "#L{:d}-L{:d}".format(lineno, lineno + len(source) - 1)
else:
linespec = ""

fn = os.path.relpath(fn, start=os.path.dirname(pandas.__file__))

if '+' in pandas.__version__:
return "http://github.com/pandas-dev/pandas/blob/master/pandas/%s%s" % (
fn, linespec)
return ("http://github.com/pandas-dev/pandas/blob/master/pandas/"
"{}{}".format(fn, linespec))
else:
return "http://github.com/pandas-dev/pandas/blob/v%s/pandas/%s%s" % (
pandas.__version__, fn, linespec)
return ("http://github.com/pandas-dev/pandas/blob/"
"v{}/pandas/{}{}".format(pandas.__version__, fn, linespec))


# remove the docstring of the flags attribute (inherited from numpy ndarray)
Expand Down