Cross-reference problem

[Midnighter]

You can find the branch with my attempts here https://github.com/Midnighter/structurizr-python/tree/add-mkdocstrings

I'm trying to use cross-references in my project but I'm running into problems. I have a markdown file to specify documentation of my class structurizr.StructurizrClient. The documentation is built and this works pretty much as expected. However, I have troubles creating my cross-references. In my main docs/index.md I'm trying to reference this documentation.

1. If I use [StructurizrClient][structurizr.StructurizrClient], I get a warning Could not find cross-reference target '[structurizr.StructurizrClient]'. (It has backticks but I don't know how to escape them here.)
2. If instead I try with [StructurizrClient][structurizr.api.structurizr_client.StructurizrClient] which is where the class really resides (I import it to the top level), then instead I get

ERROR   -  Exception in callback <bound method LiveReloadHandler.poll_tasks of <class 'livereload.handlers.LiveReloadHandler'>>
Traceback (most recent call last):
  File "/home/moritz/.pyenv/versions/3.8.5/envs/structurizr/lib/python3.8/site-packages/tornado/ioloop.py", line 905, in _run
    return self.callback()
  File "/home/moritz/.pyenv/versions/3.8.5/envs/structurizr/lib/python3.8/site-packages/livereload/handlers.py", line 69, in poll_tasks
    filepath, delay = cls.watcher.examine()
  File "/home/moritz/.pyenv/versions/3.8.5/envs/structurizr/lib/python3.8/site-packages/livereload/watcher.py", line 119, in examine
    func()
  File "/home/moritz/.pyenv/versions/3.8.5/envs/structurizr/lib/python3.8/site-packages/mkdocs/commands/serve.py", line 136, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/home/moritz/.pyenv/versions/3.8.5/envs/structurizr/lib/python3.8/site-packages/mkdocs/commands/build.py", line 292, in build
    _build_page(file.page, config, files, nav, env, dirty)
  File "/home/moritz/.pyenv/versions/3.8.5/envs/structurizr/lib/python3.8/site-packages/mkdocs/commands/build.py", line 213, in _build_page
    output = config['plugins'].run_event(
  File "/home/moritz/.pyenv/versions/3.8.5/envs/structurizr/lib/python3.8/site-packages/mkdocs/plugins.py", line 94, in run_event
    result = method(item, **kwargs)
  File "/home/moritz/.pyenv/versions/3.8.5/envs/structurizr/lib/python3.8/site-packages/mkdocstrings/plugin.py", line 232, in on_post_page
    fixed_output, unmapped = fix_refs(output, page.url, self.url_map)
  File "/home/moritz/.pyenv/versions/3.8.5/envs/structurizr/lib/python3.8/site-packages/mkdocstrings/references.py", line 201, in fix_refs
    fixed_soup = AUTO_REF.sub(fix_ref(url_map, from_url, unmapped), str(soup))
  File "/home/moritz/.pyenv/versions/3.8.5/envs/structurizr/lib/python3.8/site-packages/mkdocstrings/references.py", line 160, in inner
    url = relative_url(from_url, url_map[identifier])
  File "/home/moritz/.pyenv/versions/3.8.5/envs/structurizr/lib/python3.8/site-packages/mkdocstrings/references.py", line 107, in relative_url
    if url_a[-1] == "/":
IndexError: string index out of range

Do you know what is going on here? More details below but probably easiest to try out yourself.

Environment

System Information
==================
OS                      Linux
OS-release 5.8.0-7630-generic
Python                  3.8.5

Package Versions
================
beautifulsoup4      4.9.3
mkdocs              1.1.2
mkdocstrings       0.13.6
pip                20.2.4
pymdown-extensions  8.0.1
pytkdocs            0.9.0
setuptools         50.3.2
wheel              0.35.1

Docs tree

docs
├── development
│   ├── adr
│   │   ├── 0001-record-architecture-decisions.md
│   │   ├── 0002-version-control-our-code.md
│   │   ├── 0003-python-3-6-only.md
│   │   ├── 0004-python-package-versioning.md
│   │   ├── 0005-code-quality-assurance.md
│   │   ├── 0006-code-testing.md
│   │   ├── 0007-unit-tests.md
│   │   ├── 0008-package-structure.md
│   │   ├── 0009-use-pydantic-for-json-de-serialization.md
│   │   └── .pages
│   └── .pages
├── index.md
├── .pages
├── reference
│   ├── .pages
│   └── structurizr.StructurizrClient.md
└── requirements.txt

MkDocs config

site_name: Structurizr-Python
site_description: A Python client package for the Structurizr cloud service and on-premises installation.
site_author: Moritz E. Beber

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.inlinehilite

theme:
  name: material
  palette:
    scheme: preference
    primary: blue
    accent: cyan
  language: en
  features:
    - navigation.instant
  icon:
    repo: fontawesome/brands/github

plugins:
  - search:
      prebuild_index: true
  - awesome-pages
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          rendering:
            show_source: true
            show_root_heading: false
            show_root_toc_entry: true
            show_root_full_path: false
      watch:
        - src/structurizr

extra:
  social:
    - icon: fontawesome/brands/slack
      link: https://join.slack.com/t/structurizr/shared_invite/enQtMzkyMjY1NzMwNTkzLTcyOGI1MTZmNDQwMDQ5YmZlMThiYmU1ZTM2ZWZiMzYwMjVhNmM0OWIwNjFlZTM1YmY3YzU0ZDY2MTA1YTk5Mjg
      name: Join the Structurizr Slack
    - icon: fontawesome/brands/github
      link: https://github.com/Midnighter
      name: Moritz on GitHub
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/me_beber
      name: Moritz on Twitter
    - icon: fontawesome/brands/linkedin
      link: https://www.linkedin.com/in/moritz-beber-b597a55a/
      name: Moritz on LinkedIn

copyright: Copyright &copy 2020, Moritz E. Beber.

repo_url: https://github.com/Midnighter/structurizr-python
repo_name: Midnighter/structurizr-python

[oprypin]

The latter is correct, and the bug that you are running into then is not specific to this situation. Fix: #185

[Midnighter]

Cheers 😊

[pawamoy]

Thank you for the report @Midnighter!
Thanks @oprypin, your fix was merged 🙂

[Midnighter]

Hi, Just wanted to ask if you can please make a new release with this fix. Thank you!

[pawamoy]

Yes, there were a lot of changes since 0.13.6, we just need to make sure 0.14 won't break anything. We have a regression workflow in https://github.com/mkdocstrings/regressions that needs some improvements!

[pawamoy]

Hey @Midnighter, I just released 0.14.0b1, you can try it out and tell us if it works for you 🙂

[Midnighter]

Tested it with the 0.14 release just now and it works! 🎉 Thank you for the fix.