I am not familiar with protodoc. But I still hava a try in my local env. My initial idea was to completely hide the document with the file level 'not-implemented-hide' annotation. But I failed. 😞

In the end, I had to choose a compromise. If there is a 'not-implemented-hide' annotation, I simply ignore all messages and return a result containing only the warning info.

So, if there is a better solution, feel free to close this PR.

cc @phlax @htuch

It's probably reasonable to do it this way. Can you share a link to some generated docs with the output? Doesn't look like this is used yet.

@htuch, in fact, some APIs already use file-level annotations (although they are used incorrectly #18924 ). So we can see the final effect based on these APIs.

docs for this PR are rendered here: https://storage.googleapis.com/envoy-pr/18923/docs/index.html

/retest

Retrying Azure Pipelines:
Retried failed jobs in: envoy-presubmit

OK, this generally makes sense. I'm also curious if we could generate an empty file and just not copy that into the docs tree and skip linking?

...also curious if we could generate an empty file and just not copy that into the docs tree and skip linking?

only with what is done here - adding an orphan tag - otherwise sphinx will complain about superfluous pages

Yeah, maybe just an orphan tag then.

OK, this generally makes sense. I'm also curious if we could generate an empty file and just not copy that into the docs tree and skip linking?

This is a good idea. But I am not sure how to skip linking. 🤔 It seems that we need to update .rst index file in the /docs. It would make this approach more complex. For example:

Network filters
===============

.. toctree::
  :glob:
  :maxdepth: 2

  */empty/*
  */hide something/*
  ../../../extensions/filters/network/*/v3*/*

@htuch @phlax I made a few additional attempts, but they all failed.

If I skip whole .rst file generation of API proto, then there are some errors as follow:

ERROR: /build/tmp/_bazel_envoybuild/b570b5ccd0454dc9af9f65ab1833764d/external/envoy_api/envoy/service/discovery/v3/BUILD:7:18: protodoc external/envoy_api/envoy/service/discovery/v3/pkg/envoy/service/discovery/v3/ads.proto.rst failed: not all outputs were created or valid

If I return empty file or file only contains orphan tag, then there are some errors as follow:

/tmp/tmpn552h80o/generated/rst/api-v3/config/filter/network/network.rst:4: WARNING: toctree contains reference to document 'api-v3/extensions/filters/network/direct_response/v3/config.proto' that doesn't have a title: no link will be generated

i think the former way of not producing the file at all is preferable, but not sure exactly what is required to make it work

can i suggest just building the rst files and linking to it (the tarball) here - that way we can see what protodoc produces, and what sphinx tries to build from

i think the former way of not producing the file at all is preferable, but not sure exactly what is required to make it work

can i suggest just building the rst files and linking to it (the tarball) here - that way we can see what protodoc produces, and what sphinx tries to build from

protoc will create a .rst file for every proto file and this file will be linked to some .rst index in the /docs. The generated .rst file contains optional tags (orphan), as well as title, warnings, comments, and json formated proto msgs.

...file and this file will be linked to some .rst index in the /docs...

yep, and before sending these generated/collated rst files to sphinx, an rst.tar is created - you can build this directly like so...

$ bazel build //docs:rst

it would be helpful to look at what is inside this to figure out a way forward

... contains optional tags (orphan), as well as...

given that the way of adding an orphan tag etc isnt working out of the box, i would suggest focusing on not including the page at all

my reading of api_proto_plugin/plugin.py is that it seems possible to skip some proto files, but i forget exactly how protoc works in this respect

if we really cant get protoc/protodoc/api_proto_plugin to skip some files as desired then one option is to make the file empty and have the //docs:api_rst target strip out empty files

you can build this directly like so...

I get it and has done it. Thanks. But I still cannot find a way to solve our current problem. 🤣

my reading of api_proto_plugin/plugin.py is that it seems possible to skip some proto files

I am not sure, but may be we can filter the proto targets at the beginning.

if we really cant get protoc/protodoc/api_proto_plugin to skip some files as desired then one option is to make the file empty and have the //docs:api_rst target strip out empty files

This is also a possible idea. 🤔

I am not sure, but may be we can filter the proto targets at the beginning.

i think we have to parse with protoc to get the annotations, but im wondering whether we can return empty and skip - if not i guess its plan b with stripping empty files

I am not sure, but may be we can filter the proto targets at the beginning.

i think we have to parse with protoc to get the annotations, but im wondering whether we can return empty and skip - if not i guess its plan b with stripping empty files

But what if instead of using annotations, we aggregate the proto that needs to be skipped individually and then filter it out when we need to generate the document. Wouldn't that work?

I thought about it a bit more. Not too good. 😞

But what if instead of using annotations, we aggregate the proto that needs to be skipped individually and then filter it out when we need to generate the document. Wouldn't that work?

hmm, well, mho is that anything other than using protoc to parse and then act accordingly is a bit too automagic and best avoided

I think we can just do a custom docs copy phase that take 0 byte length files and drops them. Then we just need to have these hidden pages get turned into 0 bytes. It's a bit magical, but not that unintuitive; there aren't any valid use cases for rendering a completely blank page in the API docs.

/wait-any

This pull request has been automatically marked as stale because it has not had activity in the last 30 days. It will be closed in 7 days if no further activity occurs. Please feel free to give a status update now, ping for review, or re-open when it's ready. Thank you for your contributions!

@phlax @htuch Sorry for the delayed update. It just dawned on me today that skipping empty files is very simple. 🤣