Skip to content

Commit

Permalink
Black (#84)
Browse files Browse the repository at this point in the history 
* run "black -t py36 .""

* update flake8 config

* fix flake8 setup

* flake8 pass

* doc: update code snippet locations in create model

* update contributing guide
  • Loading branch information
@benbovy
benbovy committed Dec 18, 2019
1 parent a023af3 commit 112d50c
Show file tree
Hide file tree
Showing 31 changed files with 1,770 additions and 1,321 deletions.
126 changes: 68 additions & 58 deletions doc/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,21 +23,25 @@
print("sys.path:", sys.path)
try:
import numpy

print("numpy: %s, %s" % (numpy.__version__, numpy.__file__))
except ImportError:
print("no numpy")
try:
import attr

print("attr: %s, %s" % (attr.__version__, attr.__file__))
except ImportError:
print("no attr")
try:
import xarray

print("xarray: %s, %s" % (xarray.__version__, xarray.__file__))
except ImportError:
print("no xarray")

import xsimlab

print("xsimlab: %s, %s" % (xsimlab.__version__, xsimlab.__file__))

# -- General configuration ------------------------------------------------
Expand All @@ -50,21 +54,21 @@
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosummary',
'sphinx.ext.intersphinx',
'sphinx.ext.mathjax',
'sphinx.ext.extlinks',
'sphinx.ext.napoleon',
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
"sphinx.ext.intersphinx",
"sphinx.ext.mathjax",
"sphinx.ext.extlinks",
"sphinx.ext.napoleon",
# 'numpydoc',
'sphinx.ext.todo',
'IPython.sphinxext.ipython_directive',
'IPython.sphinxext.ipython_console_highlighting',
"sphinx.ext.todo",
"IPython.sphinxext.ipython_directive",
"IPython.sphinxext.ipython_console_highlighting",
]

extlinks = {
'issue': ('https://github.com/benbovy/xarray-simlab/issues/%s', '#'),
'pull': ('https://github.com/benbovy/xarray-simlab/pull/%s', '#')
"issue": ("https://github.com/benbovy/xarray-simlab/issues/%s", "#"),
"pull": ("https://github.com/benbovy/xarray-simlab/pull/%s", "#"),
}

autosummary_generate = True
Expand All @@ -74,21 +78,21 @@
# numpydoc_show_class_members = False

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
templates_path = ["_templates"]

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
source_suffix = ".rst"

# The master toctree document.
master_doc = 'index'
master_doc = "index"

# General information about the project.
project = 'xarray-simlab'
copyright = '2017-2018, xarray-simlab Developers'
author = 'Benoit Bovy and xarray-simlab Developers'
project = "xarray-simlab"
copyright = "2017-2018, xarray-simlab Developers"
author = "Benoit Bovy and xarray-simlab Developers"

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
Expand All @@ -109,10 +113,10 @@
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints']
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
pygments_style = "sphinx"

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
Expand All @@ -124,7 +128,7 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
html_theme = "sphinx_rtd_theme"

# otherwise, readthedocs.org uses their theme by default, so no need
# to specify it
Expand All @@ -138,13 +142,13 @@
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
html_static_path = ["_static"]


# -- Options for HTMLHelp output ------------------------------------------

# Output file base name for HTML help builder.
htmlhelp_basename = 'xarray-simlab-doc'
htmlhelp_basename = "xarray-simlab-doc"


# -- Options for LaTeX output ---------------------------------------------
Expand All @@ -153,15 +157,12 @@
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',

# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',

# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',

# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
Expand All @@ -171,19 +172,21 @@
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'xarray-simlab.tex', 'xarray-simlab Documentation',
'xarray-simlab Developers', 'manual'),
(
master_doc,
"xarray-simlab.tex",
"xarray-simlab Documentation",
"xarray-simlab Developers",
"manual",
),
]


# -- Options for manual page output ---------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'xarray-simlab', 'xarray-simlab Documentation',
[author], 1)
]
man_pages = [(master_doc, "xarray-simlab", "xarray-simlab Documentation", [author], 1)]


# -- Options for Texinfo output -------------------------------------------
Expand All @@ -192,18 +195,24 @@
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'xarray-simlab', 'xarray-simlab Documentation',
author, 'xarray-simlab', 'xarray extension for computer model simulations',
'Miscellaneous'),
(
master_doc,
"xarray-simlab",
"xarray-simlab Documentation",
author,
"xarray-simlab",
"xarray extension for computer model simulations",
"Miscellaneous",
),
]

# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
'python': ('https://docs.python.org/3.6/', None),
'numpy': ('https://docs.scipy.org/doc/numpy/', None),
'attr': ('http://www.attrs.org/en/stable/', None),
'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
'xarray': ('https://xarray.pydata.org/en/stable/', None)
"python": ("https://docs.python.org/3.6/", None),
"numpy": ("https://docs.scipy.org/doc/numpy/", None),
"attr": ("http://www.attrs.org/en/stable/", None),
"pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
"xarray": ("https://xarray.pydata.org/en/stable/", None),
}


Expand All @@ -223,16 +232,16 @@ class AccessorDocumenter(MethodDocumenter):
Specialized Documenter subclass for accessors.
"""

objtype = 'accessor'
directivetype = 'method'
objtype = "accessor"
directivetype = "method"

# lower than MethodDocumenter so this is not chosen for normal methods
priority = 0.6

def format_signature(self):
# this method gives an error/warning for the accessors, therefore
# overriding it (accessor has no arguments)
return ''
return ""


class AccessorLevelDocumenter(Documenter):
Expand All @@ -254,50 +263,50 @@ class AccessorLevelDocumenter(Documenter):
def resolve_name(self, modname, parents, path, base):
if modname is None:
if path:
mod_cls = path.rstrip('.')
mod_cls = path.rstrip(".")
else:
mod_cls = None
# if documenting a class-level object without path,
# there must be a current class, either from a parent
# auto directive ...
mod_cls = self.env.temp_data.get('autodoc:class')
mod_cls = self.env.temp_data.get("autodoc:class")
# ... or from a class directive
if mod_cls is None:
mod_cls = self.env.temp_data.get('py:class')
mod_cls = self.env.temp_data.get("py:class")
# ... if still None, there's no way to know
if mod_cls is None:
return None, []
# HACK: this is added in comparison to ClassLevelDocumenter
# mod_cls still exists of class.accessor, so an extra
# rpartition is needed
modname, accessor = rpartition(mod_cls, '.')
modname, cls = rpartition(modname, '.')
modname, accessor = rpartition(mod_cls, ".")
modname, cls = rpartition(modname, ".")
parents = [cls, accessor]
# if the module name is still missing, get it like above
if not modname:
modname = self.env.temp_data.get('autodoc:module')
modname = self.env.temp_data.get("autodoc:module")
if not modname:
if sphinx.__version__ > '1.3':
modname = self.env.ref_context.get('py:module')
if sphinx.__version__ > "1.3":
modname = self.env.ref_context.get("py:module")
else:
modname = self.env.temp_data.get('py:module')
modname = self.env.temp_data.get("py:module")
# ... else, it stays None, which means invalid
return modname, parents + [base]


class AccessorAttributeDocumenter(AccessorLevelDocumenter, AttributeDocumenter):

objtype = 'accessorattribute'
directivetype = 'attribute'
objtype = "accessorattribute"
directivetype = "attribute"

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


class AccessorMethodDocumenter(AccessorLevelDocumenter, MethodDocumenter):

objtype = 'accessormethod'
directivetype = 'method'
objtype = "accessormethod"
directivetype = "method"

# lower than MethodDocumenter so this is not chosen for normal methods
priority = 0.6
Expand All @@ -308,14 +317,15 @@ class AccessorCallableDocumenter(AccessorLevelDocumenter, MethodDocumenter):
This documenter lets us removes .__call__ from the method signature for
callable accessors like Series.plot
"""
objtype = 'accessorcallable'
directivetype = 'method'

objtype = "accessorcallable"
directivetype = "method"

# lower than MethodDocumenter; otherwise the doc build prints warnings
priority = 0.5

def format_name(self):
return MethodDocumenter.format_name(self).rstrip('.__call__')
return MethodDocumenter.format_name(self).rstrip(".__call__")


def setup(app):
Expand Down

0 comments on commit 112d50c

Please sign in to comment.