Add or suppress page breaks at will

When Sphinx generates HTML, each level-1 heading starts a new section. There's no way to put two or more level-1 sections on the same page or divide a level-1 section into two or more pages. The user needs to be able to control this. I have no experience in Sphinx with page-oriented media like PDF, but I expect they have a similar limitation and a similar requirement.

My current project is a use case. I am working on a large technical manual which describes software for a family of products. Several level-1 sections describe topics that are substantially different for each product. Thus the section is structured like this:

Power Management [level-1]
[brief introduction]

Product A Power Management [level-2]
[full discussion]

Product B Power Management [level-2]
[full discussion]

Product C Power Management [level-2]
[full discussion]

[and so on]

The level-1 section composed on a single page is very long. Any given reader is likely to use just one product, and so be interested in just one level-2 section, but there's no way they can view it alone. When they search the page for a string like "deep sleep mode" they will find instances of it for every product, and must figure out which ones are relevant on their case.

Proposal 1

Add break and nobreak options to the include directive. If an include directive includes a document that begins with a level-1 heading and it is followed by nobreak, the usual page break is suppressed. If an include directive includes a document that does not begin with a level-1 heading and it is followed by break, a break is added.

This proposal could only add or suppress a page break at the start of a source file. This limitation could be eased by allowing break and nobreak to be used with other directives.

Proposal 2

Add two new directives, break and nobreak. break can be used at any point in any file, and adds an immediate page break. nobreak, used before a level 1 heading, suppresses the normal page break. If break is used immediately before a level-1 heading, or nobreak is used anywhere else, it has no effect, and might generate a warning.

This proposal requires larger changes to the markup language (new directives instead of new options), but it allows breaks to be added or suppressed at any point, not just at the beginning of an included file.

In principle there is no reason that both proposals could not be implemented, affording the user a choice of features.

The issue names no implementation files, tests, or entry points. Start by examining how the include directive and level-1 headings produce page breaks in HTML and PDF output, then resolve whether the include options or new directives are the intended design. Done means users can explicitly add or suppress the described breaks.