Add support to ignore files

[dmulyalin]

Is your feature request related to a problem? Please describe.

Chances are Griffe might fail working with certain python modules files for various reasons, having capability to deliberately ignore certain files might be helpful to instruct Griffe to skip troublesome code.

Fo example: https://github.com/mkdocstrings/griffe/issues/66

Describe the solution you'd like

Add support for ignore_files glob patterns list to do something like this in mkdocs.yaml:

plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          selection:
            docstring_options: 
              ignore_files: 
                - path/to/foo*
                - *bar

[pawamoy]

That would not be in the docstring options, but yeah, I see what you mean :slightly_smiling_face: We can either do that or try to make sure Griffe never crashes and instead emits debug logs that explain why something is not working as expected.

[dmulyalin]

Capability to ignore files can be useful for:

• ignore troublesome code
• ignore chunks of python module that we not documenting - speed improvement? probably not too important though

not sure what other usecases could be.

Fixing issue is 100% the best course of action but ignoring files could help user to make things more or less work for them while problem being debugged, fixed, released.

[slbayer]

Here's another use case: I have a package right now which contains a resources subdirectory that I want to have distributed with the package, and that subdirectory contains a Python file which is actually a template. It will never be loaded using an import statement. And, yes, it has the .py extension. And I don't want it scanned by griffe. Perhaps an extremely odd use case, but a use case nonetheless.

[jgarte]

Just sharing something that @pawamoy had shared from the Gitter/Matrix chat that is related to ignoring files:

# scripts/exts.py
from griffe.extensions import Extension
from griffe.exceptions import LoadingError


class MyExtension(Extension):
    def on_module_instance(node, mod):
        if mod.path == "path.to.module_to_ignore":
            raise LoadingError(f"ignoring module {mod.path}")

Also see the following documentation to understand how to use this from mkdocs.yml:

https://mkdocstrings.github.io/griffe/extensions/#in-mkdocs

TLDR

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          extensions:
          - scripts/exts.py:MyExtension:
              paths: [mypkg.mymod.myobj]

[pawamoy]

Note that your mkdocs.yml example uses options. For this the extension would need to declare such options: https://mkdocstrings.github.io/griffe/extensions/#options.

[pawamoy]

I'm going to close this because our loader is now quite robust and should handle any exception with log messages.