daizutabi/mkapi

mkapi seems to misinterpret the `See Also` section of numpy docs

Closed this issue · 0 comments

smoia commented

Hey there,
I'm trying to set up mkapi to add the API of a package to its documentation. All is well, except for a module that contains a function with a See Also section in its numpy docstring.
Somehow mkapi seems to fail its interpretation, rendering (part of) it as a new H2 header:
Schermata da 2022-07-11 17-16-40

For reference:

  • The mkdocs configuration is here and the API page file itself is here. I'm using the readthedocs default mkdocs theme.
  • The function that misbehaves is here, together with the two functions after that show again a See Also H2 within a Notes section: here and here
  • I'm on python 3.7, Ubuntu 18.04, mkapi 1.0.14, mkdocs 1.2.4, and Markdown 3.2.1 - it otherwise has conflicting dependencies with flake8.
This is the dependency tree of mkapi

$ pipdeptree -p mkapi
mkapi==1.0.14
  - jinja2 [required: Any, installed: 3.0.3]
    - MarkupSafe [required: >=2.0, installed: 2.1.1]
  - markdown [required: Any, installed: 3.2.1]
    - setuptools [required: >=36, installed: 61.3.0]

This is the dependency tree of mkdocs

$ pipdeptree -p mkdocs
mkdocs==1.2.4
  - click [required: >=3.3, installed: 8.0.4]
    - importlib-metadata [required: Any, installed: 4.2.0]
      - typing-extensions [required: >=3.6.4, installed: 4.0.1]
      - zipp [required: >=0.5, installed: 3.2.0]
  - ghp-import [required: >=1.0, installed: 2.1.0]
    - python-dateutil [required: >=2.8.1, installed: 2.8.2]
      - six [required: >=1.5, installed: 1.13.0]
  - importlib-metadata [required: >=3.10, installed: 4.2.0]
    - typing-extensions [required: >=3.6.4, installed: 4.0.1]
    - zipp [required: >=0.5, installed: 3.2.0]
  - Jinja2 [required: >=2.10.1, installed: 3.0.3]
    - MarkupSafe [required: >=2.0, installed: 2.1.1]
  - Markdown [required: >=3.2.1, installed: 3.2.1]
    - setuptools [required: >=36, installed: 61.3.0]
  - mergedeep [required: >=1.3.4, installed: 1.3.4]
  - packaging [required: >=20.5, installed: 21.3]
    - pyparsing [required: >=2.0.2,!=3.0.5, installed: 2.4.5]
  - PyYAML [required: >=3.10, installed: 5.3.1]
  - pyyaml-env-tag [required: >=0.1, installed: 0.1]
    - pyyaml [required: Any, installed: 5.3.1]
  - watchdog [required: >=2.0, installed: 2.1.9]

I'm failing to use the Page Mode for other issues, but I also want to have more control on what is displayed and how.