Tuesday, August 21, 2018

Atelier now supports Sphinx 1.8

Takeshi Komiya asked the community to test Sphinx 1.8.0 preview. I found two problems, both located in my own code.

In my projects it issued a warning autodoc_default_flags is now deprecated. Please use autodoc_default_options instead. (which caused the build to fail because most projects have tolerate_sphinx_warnings set to False.

First of all I had to read the docs about autodoc_default_options to get back into why I want them. I also read the developer discussion about this change Add autodoc_default_options (#5315). Yes, specifying an empty :members: option to automodule or autoclass will automatically document members. That’s what we want. We use autodoc to generate the API automatically and we don’t want a half-automated API, we want it to always generate all members.

The issue was in atelier.sphinxconf.configure() which sets general default values.

Old default value was:

autodoc_default_flags=[ 'show-inheritance', 'members']

New value must be:

autodoc_default_options={
          'members': None,
          'show-inheritance': None}

So now atelier must set the default value depending on the Sphinx version. How to compare versions in Python elegantly? stackoverflow gives the answer:

>>> from distutils.version import LooseVersion
>>> import sphinx
>>> sphinx.__version__
'1.8.0b1'
>>> LooseVersion(sphinx.__version__) < LooseVersion("1.8")
False

Another problem was with documents that run graphviz from within a py2rst directive. For example:

.. py2rst::

   from lino import startup
   startup('lino_book.projects.lydia.settings.demo')
   from lino.api import rt
   rt.models.contacts.Partner.print_subclasses_graph()

In sphinx.ext.graphviz.Graphviz.run() Sphinx now says:

node['options'] = {
    'docname': path.splitext(self.state.document.current_source)[0],
}

This feature (“add document name to graphviz node”) was added 21 days ago in 16734bb1.

But state.document.current_source is None when the code is run from within a py2rst directive.

The problem was in InsertInputDirective where it created a new statemachine without specifying the source. Before:

content = statemachine.StringList(output.splitlines())

Now:

content = statemachine.StringList(
    output.splitlines(), self.state.document.current_source)

Summary: Atelier now supports Sphinx version is 1.8 or later. atelier.sphinxconf.configure() now checks the Sphinx version and sets the new autodoc_default_options configuration value instead of the deprecated autodoc_default_flags (if Sphinx is 1.8 or newer).

Side effects

The inv clean command now removes all .pyc files, not only dangling ones. And also .eggs directories and __pycache__ directories. The latter because they require me to type an additional “i” each time I open an __init__.py file with Emacs. So basicaly it now full cleans the generated Python cache files. Which makes the –batch option almost mandatory in practice.

I moved DjangoTemplateBridge from atelier.sphinxconf to lino.sphinxcontrib and then removed it altogether.

Started TimTools 2.0.2

The timtools sync command failed with a traceback:

Traceback (most recent call last):
  File "timtools\scripts\sync.py", line 18, in <module>
ImportError: cannot import name __url__
[292] Failed to execute script sync

Fixed and committed, but not yet released officially.