docs: use sphinx-1.5.5 for sphinx-docfx-yaml

[tmatsuo]

It should only affects docfx session.

[tmatsuo]

For the record, here is some debugging trial.

The docfx nox session has dependency as follows:

session.install("sphinx", "alabaster", "recommonmark", "sphinx-docfx-yaml")

This is done silently in the nox session. When I manually run the following:

pip install sphinx alabaster recommonmark sphinx-docfx-yaml

I get this error:

ERROR: sphinx-docfx-yaml 1.2.74 has requirement sphinx==1.5.5, but you'll have sphinx 3.2.1 which is incompatible.
Installing collected packages: sphinx-docfx-yaml
Successfully installed sphinx-docfx-yaml-1.2.74

Weirdly, the installation completes with the error message.

When I change the nox dependency to the following:

session.install("sphinx==1.5.5", "alabaster", "recommonmark", "sphinx-docfx-yaml")

The docfx nox session fails with:

nox > Running session docfx
nox > Creating virtual environment (virtualenv) using python3.8 in .nox/docfx
nox > pip install -e .
nox > pip install sphinx==1.5.5 alabaster recommonmark sphinx-docfx-yaml
nox > sphinx-build -T -N -D extensions=sphinx.ext.autodoc,sphinx.ext.autosummary,sphinx.ext.intersphinx,sphinx.ext.coverage,sphinx.ext.napoleon,sphinx.ext.todo,sphinx.ext.viewcode,recommonmark,docfx_yaml.extension -d docs/_build/doctrees/ docs/ docs/_build/html/
Running Sphinx v1.5.5
making output directory...

Traceback (most recent call last):
  File "/workspace/.nox/docfx/lib/python3.8/site-packages/sphinx/cmdline.py", line 293, in main
    app = Sphinx(srcdir, confdir, outdir, doctreedir, opts.builder,
  File "/workspace/.nox/docfx/lib/python3.8/site-packages/sphinx/application.py", line 172, in __init__
    raise VersionRequirementError(
sphinx.errors.VersionRequirementError: This project needs at least Sphinx v1.6.3 and therefore cannot be built with this version.

Sphinx version error:
This project needs at least Sphinx v1.6.3 and therefore cannot be built with this version.

Ok, when I change the needs_sphinx version in conf.py as follows:

needs_sphinx = "1.5.5"

Then the docfx session succeeds, and combined with the sphinx version above (sphinx==1.5.5), it seems that now we have method descriptions.