gapic-generator-python Error during client generation `self referenced toctree found` due to service named `services`

The appengine_admin client has a service called services . Unfortunately, services is already an implicitly reserved keyword in gapic-generator-python templates here: https://github.com/googleapis/gapic-generator-python/blob/master/gapic/templates/docs/%25name_%25version/services.rst.j2

As a result of having service.rst referencing another service.rst, I get a Sphinx error self referenced toctree found when generating the client.

sphinx.errors.SphinxWarning: /usr/local/google/home/partheniou/git/GOB/python-appengine-admin/docs/appengine_admin_v1/services.rst:self referenced toctree found. Ignored.

I'd like to propose to rename docs/<api>/services to docs/<api>/services_ when there is a service called services. For example,

You can see that there is a service called services below:

Mar 24 '21 17:03 parthea

@parthea Is this issues still relevant or do you already have a workaround for appengine_admin?

Jan 19 '22 23:01 vam-google

We have a workaround but I'd like to propose that we keep this issue open for tracking purposes as there is a bug in the generator. If we're already tracking this issue in another location then I'm happy to close it.

Jan 20 '22 22:01 parthea

I'm also seeing this issue in the generated client for cloud run here.

Mar 18 '22 11:03 parthea

Lowering priority to P3 since there is a workaround. The issue is specific to naming conflict in one concrete API. To fix it properly we would need some sort of centralized name conflict resolution (since there are many other similar issues with name conflicts in gapic-generator, all being fixed by hacks, significantly complicating maintenance of it), but it is outside of scope of this bug.

Mar 23 '22 22:03 vam-google

Just to clarify, there are 2 apis that require a manual workaround. appengine and cloud run. I'll change the label to clean up instead of bug since it is technical debt.

https://github.com/googleapis/googleapis-gen/blob/master/google/appengine/v1/google-cloud-appengine-v1-py/docs/appengine_admin_v1/services.rst

https://github.com/googleapis/googleapis-gen/blob/master/google/cloud/run/v2/run-v2-py/docs/run_v2/services.rst

Mar 24 '22 15:03 parthea

I have a prototype that works locally. It requires some changes to synthtool (post processor) as well. I will open a PR next week.

Apr 12 '23 14:04 parthea