Clarify that executor interface is public but instances are not

[dstandish]

Per dev list discussion https://lists.apache.org/thread/xv5p733j2romrhsl174fpnvfb8fw30co

[uranusjr]

Probably need to remove this from auto API generation?

/opt/airflow/docs/apache-airflow/_api/airflow/executors/index.rst: WARNING: document isn't included in any toctree

[potiuk]

Yeah. As counter-intuitive as it is, we need to exclude it in docs/conf.py

# A list of patterns to ignore when finding files
autoapi_ignore = [

[dstandish]

Confused, do we not want the executor docs autogenerated? I know we have every executor documented in core-concepts. But, if we tell auto-api to skip it, will the autogen documentation not be rendered at all? I.e. maybe this page will not be generated https://airflow.apache.org/docs/apache-airflow/stable/_api/airflow/executors/index.html ? Is that desirable?

[potiuk]

The error means that even if the documentation is autogenerated, there is no link to lead to the document. So it's not discoverable (even if generated). And yeah if we want to keep link to BaseExecutor to work - it will not work to exclude everything from executors/* because the class doc will be missing. I guess better to include the link back (maybe inline it when you talk about the other executors). But ... we do not really want to make K8S executors docstring publicly documented if they are not part of the public interface, do we?

I think that's anoth K8S / Celery other executors will be (possibly?) moved to providers - https://lists.apache.org/thread/kwwhz62lddygodpgr3fk4b9tthtld9do, the problem will be solved (as executors package might only contain BaseExecutor, constants, LocalExecutor, SequentialExecutor etc. or we could even move it out).

[dstandish]

Yeah, I suppose we can just exclude for now in any case.