There are two errors here.

1. File actually does not exist anymore. Long term fix: use autodoc instead of enumerating what to document by hand.

2. But, 1. requires that we change all references like .Period into ~period.Period.

Both 1. and 2. are independent of the style choosen, but just the way sphinx.autodoc works: it loads all modules, and when there are duplicates, it warns. Why are there duplicates? Consider:

# mymodule/helpers/parsers/myparser.py
some = "variable"

# mymodule/__init__.py
from .helpers.parsers import myparser
__all__ = ["myparser"]

This is normal: we're saying to users "hey, mymodule.myparser is the public API.

However, autodoc will see both myparser:

1. mymodule.myparser
2. mymodule.helpers.parsers.myparser

So it will warn us.

Note: it is a warn, not an error. We're considering warnings as errors to avoid these things go unnoticed.

So, strictu sensu, it has nothing —little—to do with the way we document code, appart using the ~ layout consistently. I don't know, however, how to test that we do programatically.

BTW, as you can see in #315 and previous PRs, the progressive documentation of core allows us to progressively start using autodoc to parse a module's documentation automatically (so to avoid things like this issue).