diff options
Diffstat (limited to 'sphinx')
| -rw-r--r-- | sphinx/application.py | 40 | ||||
| -rw-r--r-- | sphinx/builders/html.py | 8 | ||||
| -rw-r--r-- | sphinx/environment.py | 24 | ||||
| -rw-r--r-- | sphinx/ext/autodoc.py | 5 |
4 files changed, 69 insertions, 8 deletions
diff --git a/sphinx/application.py b/sphinx/application.py index 014a8315..89d6f623 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -237,6 +237,17 @@ class Sphinx(object): wfile.flush() def warn(self, message, location=None, prefix='WARNING: '): + """Emit a warning. + + If *location* is given, it should either be a tuple of (docname, lineno) + or a string describing the location of the warning as well as possible. + + *prefix* usually should not be changed. + + .. note:: For warnings emitted during parsing, you should use + :meth:`.BuildEnvironment.warn` since that will collect all + warnings during parsing for later output. + """ if isinstance(location, tuple): docname, lineno = location if docname: @@ -251,9 +262,22 @@ class Sphinx(object): self._log(warntext, self._warning, True) def info(self, message='', nonl=False): + """Emit an informational message. + + If *nonl* is true, don't emit a newline at the end (which implies that + more info output will follow soon.) + """ self._log(message, self._status, nonl) def verbose(self, message, *args, **kwargs): + """Emit a verbose informational message. + + The message will only be emitted for verbosity levels >= 1 (i.e. at + least one ``-v`` option was given). + + The message can contain %-style interpolation placeholders, which is + formatted with either the ``*args`` or ``**kwargs`` when output. + """ if self.verbosity < 1: return if args or kwargs: @@ -261,6 +285,14 @@ class Sphinx(object): self._log(message, self._status) def debug(self, message, *args, **kwargs): + """Emit a debug-level informational message. + + The message will only be emitted for verbosity levels >= 2 (i.e. at + least two ``-v`` options were given). + + The message can contain %-style interpolation placeholders, which is + formatted with either the ``*args`` or ``**kwargs`` when output. + """ if self.verbosity < 2: return if args or kwargs: @@ -268,6 +300,14 @@ class Sphinx(object): self._log(darkgray(message), self._status) def debug2(self, message, *args, **kwargs): + """Emit a lowlevel debug-level informational message. + + The message will only be emitted for verbosity level 3 (i.e. three + ``-v`` options were given). + + The message can contain %-style interpolation placeholders, which is + formatted with either the ``*args`` or ``**kwargs`` when output. + """ if self.verbosity < 3: return if args or kwargs: diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index b5ca56bd..5b1a7594 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -590,15 +590,17 @@ class StandaloneHTMLBuilder(Builder): if self.config.html_logo: logobase = path.basename(self.config.html_logo) logotarget = path.join(self.outdir, '_static', logobase) - if not path.isfile(logobase): - self.warn('logo file %r does not exist' % logobase) + if not path.isfile(path.join(self.confdir, self.config.html_logo)): + self.warn('logo file %r does not exist' % self.config.html_logo) elif not path.isfile(logotarget): copyfile(path.join(self.confdir, self.config.html_logo), logotarget) if self.config.html_favicon: iconbase = path.basename(self.config.html_favicon) icontarget = path.join(self.outdir, '_static', iconbase) - if not path.isfile(icontarget): + if not path.isfile(path.join(self.confdir, self.config.html_favicon)): + self.warn('favicon file %r does not exist' % self.config.html_favicon) + elif not path.isfile(icontarget): copyfile(path.join(self.confdir, self.config.html_favicon), icontarget) self.info('done') diff --git a/sphinx/environment.py b/sphinx/environment.py index 320331af..ce6b2329 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -246,10 +246,17 @@ class BuildEnvironment: self.versioning_condition = condition def warn(self, docname, msg, lineno=None): + """Emit a warning. + + This differs from using ``app.warn()`` in that the warning may not + be emitted instantly, but collected for emitting all warnings after + the update of the environment. + """ # strange argument order is due to backwards compatibility self._warnfunc(msg, (docname, lineno)) def warn_node(self, msg, node): + """Like :meth:`warn`, but with source information taken from *node*.""" self._warnfunc(msg, '%s:%s' % get_source_line(node)) def clear_doc(self, docname): @@ -698,7 +705,7 @@ class BuildEnvironment: @property def docname(self): - """Backwards compatible alias.""" + """Returns the docname of the document currently being parsed.""" return self.temp_data['docname'] @property @@ -712,16 +719,28 @@ class BuildEnvironment: return self.temp_data.get('py:class') def new_serialno(self, category=''): - """Return a serial number, e.g. for index entry targets.""" + """Return a serial number, e.g. for index entry targets. + + The number is guaranteed to be unique in the current document. + """ key = category + 'serialno' cur = self.temp_data.get(key, 0) self.temp_data[key] = cur + 1 return cur def note_dependency(self, filename): + """Add *filename* as a dependency of the current document. + + This means that the document will be rebuilt if this file changes. + + *filename* should be absolute or relative to the source directory. + """ self.dependencies.setdefault(self.docname, set()).add(filename) def note_reread(self): + """Add the current document to the list of documents that will + automatically be re-read at the next build. + """ self.reread_always.add(self.docname) def note_versionchange(self, type, version, node, lineno): @@ -740,7 +759,6 @@ class BuildEnvironment: self.app.debug('%s [filtered system message]', node.astext()) node.parent.remove(node) - def process_dependencies(self, docname, doctree): """Process docutils-generated dependency info.""" cwd = os.getcwd() diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 69c7753b..533993c5 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -1117,8 +1117,9 @@ class ClassDocumenter(ModuleLevelDocumenter): initdocstring = self.get_attr( self.get_attr(self.object, '__init__', None), '__doc__') # for new-style classes, no __init__ means default __init__ - if (initdocstring == object.__init__.__doc__ or # for pypy - initdocstring.strip() == object.__init__.__doc__): #for !pypy + if (initdocstring is not None and + (initdocstring == object.__init__.__doc__ or # for pypy + initdocstring.strip() == object.__init__.__doc__)): #for !pypy initdocstring = None if initdocstring: if content == 'init': |