Page MenuHomeSoftware Heritage

Use Sphinx 2.x to build the documentation
Closed, ResolvedPublic

Description

Development documentation fails to build since a couple of days due to the following error:

Exception occurred:
  File "/home/jenkins/workspace/DDOC/dev/swh-docs/.tox/sphinx-dev/lib/python3.7/site-packages/pkg_resources/__init__.py", line 792, in resolve
    raise VersionConflict(dist, req).with_context(dependent_req)
pkg_resources.VersionConflict: (Sphinx 1.8.5 (/home/jenkins/workspace/DDOC/dev/swh-docs/.tox/sphinx-dev/lib/python3.7/site-packages), Requirement.parse('sphinx>=2.0; python_version >= "3.0"'))

Using Sphinx 2.x to build the documentation should fix that issue.
We were still using Sphinx < 2 to build the doc due to the sphinxcontrib-images extension not being compatible with latest Sphinx releases.
The good news is that the fresh 0.9.1 release of that extension adds Sphinx 2.x support.

We should now be able to build the development documentation with latest Sphinx release.
Some new warnings should appear with that upgrade and must also be fixed to get the associated Jenkins job green again.

Event Timeline

anlambert triaged this task as Normal priority.Feb 3 2020, 2:12 PM
anlambert created this task.

D2616 removes the restriction on Sphinx version to build the doc.

As expected, some new Sphinx warnings appear after the upgrade:

/home/antoine/swh/swh-environment/swh-objstorage/swh/objstorage/multiplexer/multiplexer_objstorage.py:docstring of swh.objstorage.multiplexer.multiplexer_objstorage.ObjStorageThread.get_result_from_mailbox:10: WARNING: Field list ends without a blank line; unexpected unindent.
/home/antoine/swh/swh-environment/swh-web/swh/web/browse/utils.py:docstring of swh.web.browse.utils.get_snapshot_context:: WARNING: plusieurs cibles trouvées pour le renvoi 'NotFoundExc' : swh.vault.backend.NotFoundExc, swh.web.common.exc.NotFoundExc
/home/antoine/swh/swh-environment/swh-web/swh/web/common/origin_save.py:docstring of swh.web.common.origin_save.get_save_origin_requests:: WARNING: plusieurs cibles trouvées pour le renvoi 'NotFoundExc' : swh.vault.backend.NotFoundExc, swh.web.common.exc.NotFoundExc
/home/antoine/swh/swh-environment/swh-web/swh/web/common/origin_visits.py:docstring of swh.web.common.origin_visits.get_origin_visits:: WARNING: plusieurs cibles trouvées pour le renvoi 'NotFoundExc' : swh.vault.backend.NotFoundExc, swh.web.common.exc.NotFoundExc
/home/antoine/swh/swh-environment/swh-web/swh/web/common/service.py:docstring of swh.web.common.service.lookup_revision_log:: WARNING: plusieurs cibles trouvées pour le renvoi 'NotFoundExc' : swh.vault.backend.NotFoundExc, swh.web.common.exc.NotFoundExc
/home/antoine/swh/swh-environment/swh-web/swh/web/common/service.py:docstring of swh.web.common.service.lookup_revision_log_by:: WARNING: plusieurs cibles trouvées pour le renvoi 'NotFoundExc' : swh.vault.backend.NotFoundExc, swh.web.common.exc.NotFoundExc
/home/antoine/swh/swh-environment/swh-web/swh/web/common/service.py:docstring of swh.web.common.service.lookup_object:: WARNING: plusieurs cibles trouvées pour le renvoi 'NotFoundExc' : swh.vault.backend.NotFoundExc, swh.web.common.exc.NotFoundExc
/home/antoine/swh/swh-environment/swh-docs/docs/swh-deposit/getting-started.rst:251: WARNING: Analyse lexicale de literal_bloc impossible en "json". Mise en évidence annulée.
/home/antoine/swh/swh-environment/swh-docs/docs/swh-deposit/getting-started.rst:276: WARNING: Analyse lexicale de literal_bloc impossible en "json". Mise en évidence annulée.
/home/antoine/swh/swh-environment/swh-docs/docs/swh-deposit/specs/spec-sparse-deposit.rst:36: WARNING: Analyse lexicale de literal_bloc impossible en "xml". Mise en évidence annulée.
zack added a subscriber: zack.Feb 3 2020, 3:01 PM

tnx for debugging and fixing this!

as for the warnings, I suggest creating a dedicated "Easy hack" for it

as for the warnings, I suggest creating a dedicated "Easy hack" for it

I will handle the current ones (I do not like to see red circles on Jenkins) but new warnings will necessarily appear as the swh codebase evolves.

I will create a task with the detailed instructions to check if there is currently Sphinx warnings
in the current development documentation and inform that they should be fixed.

I will handle the current ones (I do not like to see red circles on Jenkins)

Eventually, I will only handle warnings from swh-web and let the other ones to swh newcomers (for instance, GSOC students).
I have created T2265 as "Easy hack" task with detailed instructions on how to build the doc locally.

Closing this now.

anlambert closed this task as Resolved.Feb 3 2020, 4:02 PM
anlambert claimed this task.