search

mkdocstrings / griffe

Signatures for entire Python programs. Extract the structure, the frame, the skeleton of your project, to generate API documentation or find breaking changes in your API.
https://mkdocstrings.github.io/griffe
ISC License
304 stars 41 forks source link

bug: parsing of annotations placed after parameters section fails #260

Closed HugoMVale closed 6 months ago

HugoMVale commented 6 months ago

Description of the bug

image

To Reproduce

The doc of foo in the example below shows the problem 

 git clone https://github.com/HugoMVale/griffe-issue
 cd griffe-issue
 python -m venv .venv
 . .venv/bin/activate
 pip install -r requirements.txt
 mkdocs serve

Full traceback

(.venv) PS C:\Code\griffeissue> mkdocs build -v
DEBUG   -  Loading configuration file: C:\Code\griffeissue\mkdocs.yml
DEBUG   -  Loaded theme configuration for 'material' from 'C:\Code\griffeissue\.venv\lib\site-packages\material\templates\mkdocs_theme.yml': {'language':
           'en', 'direction': None, 'features': [], 'font': {'text': 'Roboto', 'code': 'Roboto Mono'}, 'icon': None, 'favicon': 'assets/images/favicon.png',
           'static_templates': ['404.html']}
DEBUG   -  Config value 'config_file_path' = 'C:\\Code\\griffeissue\\mkdocs.yml'
DEBUG   -  Config value 'site_name' = 'My Docs'
DEBUG   -  Config value 'nav' = None
DEBUG   -  Config value 'pages' = None
DEBUG   -  Config value 'exclude_docs' = None
DEBUG   -  Config value 'not_in_nav' = None
DEBUG   -  Config value 'site_url' = None
DEBUG   -  Config value 'site_description' = None
DEBUG   -  Config value 'site_author' = None
DEBUG   -  Config value 'theme' = Theme(name='material', dirs=['C:\\Code\\griffeissue\\.venv\\lib\\site-packages\\material\\templates',
           'C:\\Code\\griffeissue\\.venv\\lib\\site-packages\\mkdocs\\templates'], static_templates={'404.html', 'sitemap.xml'}, name='material',
           locale=Locale('en'), language='en', direction=None, features=[], font={'text': 'Roboto', 'code': 'Roboto Mono'}, icon=None,
           favicon='assets/images/favicon.png')
DEBUG   -  Config value 'docs_dir' = 'C:\\Code\\griffeissue\\docs'
DEBUG   -  Config value 'site_dir' = 'C:\\Code\\griffeissue\\site'
DEBUG   -  Config value 'copyright' = None
DEBUG   -  Config value 'google_analytics' = None
DEBUG   -  Config value 'dev_addr' = _IpAddressValue(host='127.0.0.1', port=8000)
DEBUG   -  Config value 'use_directory_urls' = True
DEBUG   -  Config value 'repo_url' = None
DEBUG   -  Config value 'repo_name' = None
DEBUG   -  Config value 'edit_uri_template' = None
DEBUG   -  Config value 'edit_uri' = None
DEBUG   -  Config value 'extra_css' = []
DEBUG   -  Config value 'extra_javascript' = []
DEBUG   -  Config value 'extra_templates' = []
DEBUG   -  Config value 'markdown_extensions' = ['toc', 'tables', 'fenced_code', 'admonition']
DEBUG   -  Config value 'mdx_configs' = {}
DEBUG   -  Config value 'strict' = False
DEBUG   -  Config value 'remote_branch' = 'gh-pages'
DEBUG   -  Config value 'remote_name' = 'origin'
DEBUG   -  Config value 'extra' = {}
DEBUG   -  Config value 'plugins' = {'material/search': <material.plugins.search.plugin.SearchPlugin object at 0x00000212AEDAFE80>, 'mkdocstrings':
           <mkdocstrings.plugin.MkdocstringsPlugin object at 0x00000212AEDAFF40>}
DEBUG   -  Config value 'hooks' = {}
DEBUG   -  Config value 'watch' = []
DEBUG   -  Config value 'validation' = {'nav': {'omitted_files': 20, 'not_found': 30, 'absolute_links': 20}, 'links': {'not_found': 30, 'absolute_links': 20, 
           'unrecognized_links': 20}}
DEBUG   -  Running 1 `startup` events
DEBUG   -  Running 2 `config` events
DEBUG   -  Looking for translations for locale 'en'
DEBUG   -  No translations found here: 'C:\Code\griffeissue\.venv\lib\site-packages\mkdocs\templates\locales'
DEBUG   -  No translations found here: 'C:\Code\griffeissue\.venv\lib\site-packages\material\templates\locales'
DEBUG   -  Looking for translations for locale 'en'
DEBUG   -  No translations found here: 'C:\Code\griffeissue\.venv\lib\site-packages\mkdocs\templates\locales'
DEBUG   -  No translations found here: 'C:\Code\griffeissue\.venv\lib\site-packages\material\templates\locales'
DEBUG   -  Looking for translations for locale 'en'
DEBUG   -  No translations found here: 'C:\Code\griffeissue\.venv\lib\site-packages\mkdocs\templates\locales'
DEBUG   -  No translations found here: 'C:\Code\griffeissue\.venv\lib\site-packages\material\templates\locales'
DEBUG   -  mkdocstrings: Adding extension to the list
DEBUG   -  mkdocstrings: Added a subdued autorefs instance <mkdocs_autorefs.plugin.AutorefsPlugin object at 0x00000212AF011660>
DEBUG   -  mkdocs_autorefs: Adding AutorefsExtension to the list
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: C:\Code\griffeissue\site
DEBUG   -  Looking for translations for locale 'en'
DEBUG   -  No translations found here: 'C:\Code\griffeissue\.venv\lib\site-packages\mkdocs\templates\locales'
DEBUG   -  No translations found here: 'C:\Code\griffeissue\.venv\lib\site-packages\material\templates\locales'
DEBUG   -  Reading markdown pages.
DEBUG   -  Reading: index.md
DEBUG   -  Running 1 `page_markdown` events
DEBUG   -  mkdocstrings: Matched '::: main.foo'
DEBUG   -  mkdocstrings: Using handler 'python'
DEBUG   -  mkdocstrings: Collecting data
DEBUG   -  griffe: Found main: loading
DEBUG   -  griffe: Loading path C:\Code\griffeissue\main.py
DEBUG   -  griffe: Iteration 1 finished, 0 aliases resolved, still 0 to go
DEBUG   -  mkdocstrings: Updating handler's rendering env
DEBUG   -  mkdocstrings: Rendering templates
DEBUG   -  mkdocstrings: python\templates\material\function.html: Rendering main.foo
WARNING -  griffe: main.py:20: Could not parse line '!!! note'
DEBUG   -  mkdocstrings: python\templates\material\docstring.html: Rendering docstring
DEBUG   -  mkdocstrings: python\templates\material\docstring\parameters.html: Rendering parameters section
DEBUG   -  mkdocstrings: python\templates\material\docstring\returns.html: Rendering returns section
DEBUG   -  Running 1 `page_content` events
DEBUG   -  Running 1 `env` events
DEBUG   -  mkdocstrings: Creating inventory file objects.inv
DEBUG   -  Copying static assets.
DEBUG   -  Copying media file: 'assets/images/favicon.png'
DEBUG   -  Copying media file: 'assets/javascripts/bundle.1e8ae164.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/bundle.1e8ae164.min.js.map'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.ar.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.da.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.de.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.du.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.el.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.es.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.fi.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.fr.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.he.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.hi.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.hu.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.hy.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.it.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.ja.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.jp.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.kn.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.ko.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.multi.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.nl.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.no.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.pt.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.ro.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.ru.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.sa.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.stemmer.support.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.sv.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.ta.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.te.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.th.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.tr.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.vi.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/min/lunr.zh.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/tinyseg.js'
DEBUG   -  Copying media file: 'assets/javascripts/lunr/wordcut.js'
DEBUG   -  Copying media file: 'assets/javascripts/workers/search.b8dbb3d2.min.js'
DEBUG   -  Copying media file: 'assets/javascripts/workers/search.b8dbb3d2.min.js.map'
DEBUG   -  Copying media file: 'assets/stylesheets/main.bcfcd587.min.css'
DEBUG   -  Copying media file: 'assets/stylesheets/main.bcfcd587.min.css.map'
DEBUG   -  Copying media file: 'assets/stylesheets/palette.06af60db.min.css'
DEBUG   -  Copying media file: 'assets/stylesheets/palette.06af60db.min.css.map'
DEBUG   -  Building theme template: 404.html
DEBUG   -  Building theme template: sitemap.xml
DEBUG   -  Gzipping template: sitemap.xml
DEBUG   -  Building markdown pages.
DEBUG   -  Building page index.md
DEBUG   -  Running 1 `page_context` events
DEBUG   -  Running 1 `post_page` events
DEBUG   -  mkdocs_autorefs: Fixing references in page index.md
DEBUG   -  Running 2 `post_build` events
DEBUG   -  mkdocstrings: Tearing handlers down
INFO    -  Documentation built in 0.64 seconds
(.venv) PS C:\Code\griffeissue>

Expected behavior

Annotations placed after the parameters section should also work (they used to!).

Environment information

(.venv) PS C:\Code\griffeissue> griffe --debug-info  # | xclip -selection clipboard
- __System__: Windows-10-10.0.22631-SP0
- __Python__: cpython 3.10.10
- __Environment variables__:
- __Installed packages__:
  - `griffe` v0.42.2
pawamoy commented 6 months ago

Hello @HugoMVale, thanks for the report :slightly_smiling_face:

Some time ago we updated our Numpydoc-style docstring parser to improve its compliance with the official style guide, which does not explicitly allow prose in between or after known sections.

Admonitions like !!! info are prose (Markdown markup), and therefore are not supported anymore after known sections like Parameters, etc..

Instead, please use the style-specific support for admonitions:

def foo(x: float) -> float:
    """Foo function.

    Note
    ----
    This works.

    Parameters
    ----------
    x : float
        Number

    Returns
    -------
    float
        Square of number.

    Note
    ----
    This works too.

    """
    return x**2

Closing, but feel free to comment further!