include directive: start from alternative heading level

[comabrewer]

Thanks for the great project. I perfectly fits the use case I have, with one minor issue.

TL;DR: Is it possible to fix or ignore non-consecutive header levels?

For a group of related projects, I want the contributors to write all the documentation in a single README.md. From the README and the docstrings, I generate the online docs with Sphinx and MyST. I want the sections of the README to end up in separate documents of my generated docs. The docs/ directory is populated with generic stub files that are generated by a cookiecutter.

The README always has the same sections (second level):

# project-name
## Usage
## Installation
## Changelog
### 0.1.0 (2020-10-01)
## Contributing
...

From this, I generate separate pages (e.g. changelog.md):

# Changelog

```{include} ..\README.md
:start-after: "## Changelog"
:end-before: "## Contributing"

My index.md:

# project-name

```{toctree}
installation.md
usage.md
api.md
changelog.md
contribution.md
```

What was a level 2 heading now should be a level 1 heading in the split documents. When building the docs, MyST emits the warning Non-consecutive header level increase because of this. The warning is correct and intended, see #71, but is there any way around this? I want to treat Sphinx warnings as errors, because it has proven very helpful in the past.

Possible solutions:

• Is it possible to disable the specific warning? Sphinx offers suppress_warnings, but I couldn't figure out the type for this warning.
• Is there a possibility to modify header levels of the included documents, or to set the initial level from 0 to 1?

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[chrisjsewell]

thanks, I'll have to think about this one, perhaps as part of the include directive there could be an option to set the initial header level

[choldgraf]

Maybe as a first step we can figure out what warning class is raised here so that you could use the suppress warnings config that you mentioned. Surely somebody else in the Sphinx world has had the same problem before? Maybe there’s a stackoverflow question about this or something?

[chrisjsewell]

No this warning arises directly from MyST-Parser: https://github.com/executablebooks/MyST-Parser/blob/4e02629f5fb575fdd733ca43891bebb2e312ad00/myst_parser/docutils_renderer.py#L258-L266

correctly, because for example

# title
## sub-title

# title
### sub-title

## title
### sub-title

all are parsed to sphinx AST:

<section>
  <section>

which will then be always rendered as

# title
## sub-title

so it is not possible to conserve the original levels, if they are not consecutive and starting from 1

include is a special case though, since you are inserting into an existing document, it does make sense to potentially start at a level greater than 1

[chrisjsewell]

With https://github.com/executablebooks/MyST-Parser/pull/313, this warning can now be suppressed.

I will leave this issue open though, as for include it would probably be better to have an extra option to "add/minus x" to the initial heading level

[comabrewer]

Thanks a lot for picking this up. Being able to suppress warnings does the job for the moment. Your suggestion sounds even nicer.

[webknjaz]

Sounds like a great idea but I'm a bit concerned about the inconsistency with the Sphinx-native directive settings. I think if this is to be implemented, maybe there should be a PR submitted to the Sphinx upstream simultaneously so that it's consistent between RST and MD.

[chrisjsewell]

Myst's include now supports an offset-heading option https://myst-parser.readthedocs.io/en/latest/syntax/organising_content.html#inserting-other-documents-directly-into-the-current-document

maybe there should be a PR submitted to the Sphinx upstream simultaneously so that it's consistent between RST and MD.

Others are welcome to try, but I have rarely found much join in trying to upstream changes like this