docs: building docs has warnings and depends on exact paths #685

The docs can currently only be built from the docs folder, leading to a quite unintuitive way to build the docs using:
cd docs/source && python -m sphinx . ../build && cd ../..

Generally, it should also be possible to build the docs using:

python -m sphinx docs/source docs/build or directly make html

This requires some adjustments in the used plugins.

• sphinx-argparse does not resolve links from the srcdir
  • A fix is available here: the extension should primarly resolve the srcdir. sphinx-doc/sphinx-argparse#73
• nbsphinx-link creates path warnings and does not resolve links from the srcdir as well
  • a fix for this is available here: use pathlib where possible and fix warnings vidartf/nbsphinx-link#26

Besides of this, some build warnings exist as well:

• pickling environment... WARNING: cannot cache unpickable configuration value: 'nbsphinx_custom_formats' (because it contains a function, class, or module object) [config.cache] is also fixed with use pathlib where possible and fix warnings vidartf/nbsphinx-link#26
• Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead. - this also comes from usage of doc2path in our conf.py
• some links in ipynb files are not working as the reference slug used in # 3.2 my section should be #3.2-my-section and must include the docs to be parsed correctly
• some paths did have a windows backslash which is not interpreted correctly by sphinx/rtd