enable start-at for include

[joroeinvoca]

Is your feature request related to a problem? Please describe.
I have some files that throw the "isn't included in any toctree" warning. They are referenced via a somewhat wildcarded "include" as part of a home-grown templating solution. Unfortunately, if I add :orphan: to the top of the files that throw the warning, it is rendered in my output.

Describe the solution you'd like
I'd like to be able to use start-at with include so I can start at the first relevant part of the file and skip the :orphan:

Describe alternatives you've considered
Alternatively I'd love for the :orphan: to just not render, but it seems like if a file is referenced in some way by include, that's just how it works. I can't use :start-after: orphan because it leaves a blank line at the top when rendered (at least it doesn't say :orphan: at the top!)

Another option would, I suppose, be a file trim function to trim the empty line(s) at the start and end of whatever is referenced by the include.

[picnixz]

From what I understand, you want to include a lot of files (e.g., by specifying include_patterns in the configuration file), but you want to skip some "orphan" files by marking them using :orphan:? If this is the case, use exclude_patterns = ['file_to_exclude'] instead.

If you want to use the include directive, e.g., .. include:: file.txt, but only include, say lines 1 to 10 (indexed starting from 1) of file.txt, you can use :start-line: 0 and :end-line: 10 (see include directive). Sphinx should support these directive options, but I haven't checked myself.

If you want to include "blocks" from a file, you need to use multiple .. include:: directives since you cannot specify a list of slices in a single directive. This could however be a feature to be implemented (again, I did not check whether Sphinx supports that or not).

[joroeinvoca]

I don't think I want to use the exclude_patterns because there are a bunch of files without that consistent of a naming scheme.

I can't use static line numbers because the include is in a file that is called many times, once for each orphaned file. The file where the include is has this syntax:
.. include:: _:page:

where :page: is substituted in as needed

I'd like to just dynamically skip the :orphan: reference and the empty line(s) below it and start with the real content of the files, since otherwise the :orphan: tag and blank line underneath it are rendered on my site. While :start-after: works, I can't get that to omit the empty line between :orphan: and my desired content. Thus I'd like to use :start-at: because I know what the first thing in each file is that I'd like rendered.

I think my other option is to use some sort of hidden toctree but that seemed like even more of a hack so I have not tried implementing that yet. I'd just like for my builds to not have 80+ warnings each time.

[picnixz]

By looking at your project developer-doc, I think I understand what you want to do.

What I understood is as follows:

• You have some template file (_api_endpoint.txt) which would be rendered using some variables declared by the .. api_endpoint::.
• Inside the template, you have a reference to .. include:: _:page:.tmp. So, the issue is that this "page" is the one raising warnings (e.g., _get_advertiser_campaigns.rst).
• The page you are actually including is _get_advertiser_campaigns.tmp (I think?) so it appears that you are creating a new file (or copy). Why don't you remove the :orphan: when you create the .tmp file ? or why don't you exclude all .tmp files using exclude_patterns ?

By the way, you tell me that you cannot use an absolute line number, but since your included files start with :orphan:, why can't you use it ? Since you seem to put :orphan: at the top of the page, why not using :start-line: 2 ?

I am not very confident in changing the docutils directive itself because it means to override the docutils.parsers.rst.directives.misc.Include class. On the other hand, I still believe that :start-line: should be sufficient.

If you want to suppress warnings about toc, you can just add suppress_warnings = ['toc'] in your config.py and you won't get any warnings about those "bad" files by the way (although it will suppress all warnings related to toc).