0.3.19: sphinx 4.0.3 warnings

[kloczek]

At the moment sphinx 4.0.3 fails on building LibCST documentation so I've opened sphinx-doc/sphinx#9432 however in that ticket there are some warnings as well

+ /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx
running build_sphinx
Running Sphinx v4.0.3
making output directory... done
[autosummary] generating autosummary for: best_practices.rst, codemods.rst, codemods_tutorial.rst, experimental.rst, helpers.rst, index.rst, matchers.rst, matchers_tutorial.ipynb, metadata.rst, metadata_tutorial.ipynb, motivation.rst, nodes.rst, parser.rst, scope_tutorial.ipynb, tutorial.ipynb, visitors.rst, why_libcst.rst
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 17 added, 0 changed, 0 removed
reading sources... [100%] why_libcst
/home/tkloczko/rpmbuild/BUILD/LibCST-0.3.19/libcst/metadata/full_repo_manager.py:docstring of libcst.metadata.full_repo_manager.FullRepoManager.__init__:7: WARNING: Field list ends without a blank line; unexpected unindent.
/home/tkloczko/rpmbuild/BUILD/LibCST-0.3.19/libcst/metadata/full_repo_manager.py:docstring of libcst.metadata.full_repo_manager.FullRepoManager.__init__:10: WARNING: Unexpected indentation.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-libcst.3 { why_libcst motivation tutorial metadata_tutorial scope_tutorial matchers_tutorial codemods_tutorial best_practices parser nodes visitors metadata matchers codemods helpers experimental } failed

Exception occurred:
  File "/usr/lib/python3.8/site-packages/sphinx/writers/manpage.py", line 463, in unknown_visit
    raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
NotImplementedError: Unknown node: CodeAreaNode
The full traceback has been saved in /tmp/sphinx-err-szrv8tbr.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

[astrojuanlu]

sphinx-doc/sphinx#9432 was closed and deemed not a Sphinx bug. I think this issue is a close duplicate of spatialaudio/nbsphinx#483

Could you test if this NotImplementedError appears with other versions of Sphinx, without changing the nbsphinx dependency? I would find it very weird if it only happened with 4.0.3.

Also, 4.1.0 had a couple of regressions and you might want to wait for 4.1.1.

[mgeier]

nbsphinx author here.

I've never used the manpage builder, so I wouldn't be surprised if nbsphinx doesn't work with it.

This is indeed similar to spatialaudio/nbsphinx#483.

If you want to make the manpage builder work with nbsphinx, please make a PR. I'm happy to help if I can, but I won't implement it myself.

[kloczek]

Those warnings are not man roff outpt specyfic

[tkloczko@barrel LibCST-0.3.20]$ /usr/bin/python3 setup.py build_sphinx -b html --build-dir build/sphinx
running build_sphinx
Running Sphinx v4.1.2
making output directory... done
[autosummary] generating autosummary for: best_practices.rst, codemods.rst, codemods_tutorial.rst, experimental.rst, helpers.rst, index.rst, matchers.rst, matchers_tutorial.ipynb, metadata.rst, metadata_tutorial.ipynb, motivation.rst, nodes.rst, parser.rst, scope_tutorial.ipynb, tutorial.ipynb, visitors.rst, why_libcst.rst
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 17 source files that are out of date
updating environment: [new config] 17 added, 0 changed, 0 removed
reading sources... [100%] why_libcst
/home/tkloczko/rpmbuild/BUILD/LibCST-0.3.20/libcst/metadata/full_repo_manager.py:docstring of libcst.metadata.full_repo_manager.FullRepoManager.__init__:7: WARNING: Field list ends without a blank line; unexpected unindent.
/home/tkloczko/rpmbuild/BUILD/LibCST-0.3.20/libcst/metadata/full_repo_manager.py:docstring of libcst.metadata.full_repo_manager.FullRepoManager.__init__:10: WARNING: Unexpected indentation.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] why_libcst
generating indices... genindex done
copying notebooks ... [100%] tutorial.ipynb
highlighting module code... [100%] libcst.metadata.wrapper
writing additional pages... search done
copying images... [100%] _static/img/python_scopes.png
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 2 warnings.

You can check all formats by:

for i in html dirhtml singlehtml htmlhelp qthelp devhelp epub applehelp latex man texinfo text gettext doctest linkcheck xml pseudoxml; do /usr/bin/python3 setup.py build_sphinx -b $i --build-dir build/sphinx; done

About PR .. sorry but I have no idea how to fix that.

[mgeier]

Those warnings just complain about the docstring formatting. You should indent broken lines (those starting with :class:), then the warnings should go away.

[MapleCCC]

I think this issue is the same with #749. With the landing of #750, this issue can be closed now.

[kloczek]

Yep