Page MenuHomeSoftware Heritage
Create Task
Maniphest T2264

Use Sphinx 2.x to build the documentation
Closed, MigratedEdits Locked
Actions

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.

Related Objects

Event Timeline

anlambert triaged this task as Normal priority.Feb 3 2020, 2:12 PM
anlambert created this task.
anlambert mentioned this in D2616: Use latest sphinx version to build the doc.Feb 3 2020, 2:32 PM
anlambert added a comment.Feb 3 2020, 2:35 PM

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.
anlambert mentioned this in rDDOCf59cc0e489b0: Use latest sphinx version to build the doc.Feb 3 2020, 2:53 PM
anlambert mentioned this in D2618: Fix Sphinx 2.x warnings.Feb 3 2020, 2:59 PM
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

anlambert added a comment.Feb 3 2020, 3:22 PM

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.

anlambert added a comment.Feb 3 2020, 4:02 PM

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.
gitlab-migration changed the task status from Resolved to Migrated.Jan 8 2023, 4:29 PM
gitlab-migration claimed this task.
gitlab-migration added a subscriber: gitlab-migration.

This task has been migrated to GitLab.

About · Developer information · Legal