comp: tutorial: replace cpp:struct: with cpp:class:

[marc-hb]

I tested most sphinx versions between 2.0.0 (when cpp:struct: was
introduced) and version 2.3.1 and cpp:struct: crashes them all with
the same traceback below. I don't know why but considering 2.4.0 was
released only in late 2019, let's just avoid the issue and use the older
cpp:class: instead. This also avoids bumping the sphinx version
in scripts/requirements.

For information I used doxygen version 1.8.15 and my generated file
doc/doxygen/xml/structcomp__copy__limits.xml has this line near the top:
<compounddef id="structcomp__copy__limits" kind="struct" language="C++" prot="public">

The world "class" is nowhere in that generated file.

Fixes: e609daf ("comp: tutorial: update part I)

References:

http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing
https://pypi.org/project/Sphinx/#history

Traceback:

Type is struct, declType is class

Traceback (most recent call last):
  File "/usr/lib/python3.7/site-packages/sphinx/cmd/build.py", line 284, in build_main
    app.build(args.force_all, filenames)
  File "/usr/lib/python3.7/site-packages/sphinx/application.py", line 345, in build
    self.builder.build_update()
  File "/usr/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 319, in build_update
    len(to_build))
  File "/usr/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 382, in build
    self.write(docnames, list(updated_docnames), method)
  File "/usr/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 560, in write
    nproc=self.app.parallel - 1)
  File "/usr/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 586, in _write_parallel
    doctree = self.env.get_and_resolve_doctree(firstname, self)
  File "/usr/lib/python3.7/site-packages/sphinx/environment/__init__.py", line 554, in get_and_resolve_doctree
    self.apply_post_transforms(doctree, docname)
  File "/usr/lib/python3.7/site-packages/sphinx/environment/__init__.py", line 601, in apply_post_transforms
    transformer.apply_transforms()
  File "/usr/lib/python3.7/site-packages/sphinx/transforms/__init__.py", line 90, in apply_transforms
    super().apply_transforms()
  File "/usr/lib/python3.7/site-packages/docutils/transforms/__init__.py", line 172, in apply_transforms
    transform.apply(**kwargs)
  File "/usr/lib/python3.7/site-packages/sphinx/transforms/post_transforms/__init__.py", line 45, in apply
    self.run(**kwargs)
  File "/usr/lib/python3.7/site-packages/sphinx/transforms/post_transforms/__init__.py", line 92, in run
    typ, target, node, contnode)
  File "/usr/lib/python3.7/site-packages/sphinx/domains/cpp.py", line 7277, in resolve_xref
    target, node, contnode)[0]
  File "/usr/lib/python3.7/site-packages/sphinx/domains/cpp.py", line 7217, in _resolve_xref_inner
    if not checkType():
  File "/usr/lib/python3.7/site-packages/sphinx/domains/cpp.py", line 7216, in checkType
    assert False
AssertionError

Signed-off-by: Marc Herbert marc.herbert@intel.com

[mmaka1]

Oh, have not tried that with minimum ver. required. Btw, what is the reason for supporting a version that is 2y old? Is there any plan for upgrades? 2.4.4 was the version installed by default by pip a couple of weeks ago on my local system.

[marc-hb]

Btw, what is the reason for supporting a version that is 2y old? Is there any plan for upgrades?

Hi @mmaka1 , I don't know the process for maintaining script/requirements.txt. I just saw right now that @deb-intel hardcoded the versions again in recent commit 79acd2a.

I understand we generally don't want to waste time (like I did) to support many different versions, on the other hand I already spent this time, this patch is only two lines long, 2.4.0 was released only 4 months ago and it's nicer not to force users to use one virtualenv per project that uses sphinx.

[intelkevinputnam]

The latest version of Sphinx on PyPI is actually 3.0.1, so it makes sense to bound it. The tech content team are already supporting multiple projects with different dependencies, and we don't have time to vet them all. Setting the dependencies explicitly means anyone who clones the repo can get to work right away.

[intelkevinputnam]

Also, Travis-CI depends on the requirements.txt. If upstream changes to the latest version of Sphinx break the build, a failed deployment might be the first time anyone realizes it.

[marc-hb]

Thanks @intelkevinputnam but I still confused about the version policies. I'm answering in PR #198 which is the only PR with some earlier discussion on this topic.