Make conf. files linter-compliant

[rkratky]

With the current setup of custom_conf.py and build_requirements.py, the Mypy linter throws an error because it doesn't see the build_requirements.py file (when it's in the .sphinx directory -- for some reason, it ignores the sys.path.append('.sphinx/') config; see How imports are found). Moving build_requirements.py (back) into the same dir as the conf. files solves the problem, but not quite.

It only works if the docs are in the root dir of the repo (i.e. not under docs/, for example). This is because build_requirements.py opens requirements.txt, but the RTD build system doesn't find this file:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/canonical-project/checkouts/NN/docs/build_requirements.py", line 123, in <module>
    with open(".sphinx/requirements.txt", "w") as requirements_file:
FileNotFoundError: [Errno 2] No such file or directory: '.sphinx/requirements.txt'

Unless the path to open it is specified as:

    with open("docs/.sphinx/requirements.txt", "w") as requirements_file:

(Where docs/ is the dir under which the custom_conf.py and build_requirements.py files are.)

However, such a change (adding docs/ to the path to open requirements.txt) breaks the CI checks on GitHub because they already have the path specified in automatic-doc-checks.yml, and Python is run from there:

Traceback (most recent call last):
  File "/home/runner/work/project/project/docs/build_requirements.py", line 123, in <module>
    with open("docs/.sphinx/requirements.txt", "w") as requirements_file:
FileNotFoundError: [Errno 2] No such file or directory: 'docs/.sphinx/requirements.txt'
make: *** [Makefile:42: .sphinx/requirements.txt] Error 1

For the time being, I "fixed" this by adding the following condition to build_requirements.py:

    on_rtd = os.environ.get("READTHEDOCS") == "True"
    if on_rtd:
        reqs_location = re.sub("^/?", "", html_context["github_folder"])
    else:
        reqs_location = ""
    with open(reqs_location + ".sphinx/requirements.txt", "w") as requirements_file:

(I'm taking the docs dir as specified in custom_conf.py and stripping the leading / from it.)

But it seems brittle (and it's not really a solution for the underlying problem, which is that Mypy chokes on the default setup.

(I suppose this might be worth considering together with #197.)

[akcano]

Will address this for the extension-based SP, along with other linting/formatting issues.