pytypes.h: fix docs generation

[ahesford]

[Note: I'm tagging @michaeljones as the breathe maintainer in case this is actually a bug in that project.]

Not sure if this is a pybind11 problem or a breathe problem, but man generation with

make -C docs man

fails for breathe>=4.17.0 (with Sphinx ver. 3.0.3) with the following error:

/home/ahesford/software/pybind11/docs/reference.rst:52: WARNING: Duplicate declaration, str : public object
/home/ahesford/software/pybind11/docs/reference.rst.rst:52: WARNING: C++ declarations inside functions are not supported. Parent function is str

Exception occurred:
  File "/usr/lib/python3.8/site-packages/breathe/renderer/sphinxrenderer.py", line 408, in run_directive
    rst_node = nodes[1]
IndexError: list index out of range
The full traceback has been saved in /tmp/sphinx-err-gole5l1d.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!
make: *** [Makefile:141: man] Error 2
make: Leaving directory '/home/ahesford/software/pybind11/docs'

The problem is fixed by excluding the following two constructor definitions from the pytypes doxygen group in pytypes.h:

inline bytes::bytes(const pybind11::str &)
inline str:str(const bytes&)

Although builds with breathe==4.16.0 did not explicitly fail, it appears that the output man page omitted class declarations intended for inclusion in the pytypes doxygen group that followed the aforementioned constructor definitions. Thus, it seems that breathe just prematurely terminated that group.

[rwgk]

Looks like a good workaround to me. It would be nice to add a one-line comment to explain, maybe:

// Closing pytypes group and reopening below to work around a documentation tool issue (seen with breathe 4.17.0).

[ahesford]

Comment added in the latest push.

[rwgk]

Looks good to me. Thanks!

[wjakob]

Fascinating -- thanks for tracking this down @ahesford.