Mkdocs unable to find modules

Question

I'm trying to generate automated documentation, using :
mkdocs = "^1.4.2"
mkdocstrings = "0.19.0"
mkdocs-material = "8.5.8"
mkdocstrings-python = "0.7.1"

my mkdocs.yml looks like this :

site_name: Optimization Services Documentation
site_url: "https://example.com"

theme:
  name: "material"
nav:
  - 'index.md'
  - 'reference.md'
plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          setup_commands:
            - import sys
            - sys.path.append('../')
          selection:
            new_path_syntax: true

index.md is still the default file generated by mkdocs new.

reference.md looks like this :

# Reference
::: modelling.constraints

and modelling.constraints.py:

def init_constraints(groupes_chantiers: list[GroupeChantiers],
                     digraph_precedence: nx.DiGraph,
                     graph_coactivite: nx.Graph,
                     model: cp_model.CpModel,
                     **kwargs) -> None:
    """
    Adds constraints to cp_model
    Args:
        groupes_chantiers: 
        digraph_precedence: 
        graph_coactivite: 
        model: 

    Returns: None

    """
    pass

When I'm trying to build documentation, mkdocs serve returns:

INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  DeprecationWarning: 'selection' and 'rendering' are deprecated and merged into a single 'options' YAML key
              File "C:\Users\9821390Z.COMMUN\AppData\Local\pypoetry\Cache\virtualenvs\optimisation-KWHapjG2-py3.9\lib\site-packages\mkdocstrings\extension.py", line 121, in run
                html, handler, data = self._process_block(identifier, block, heading_level)
              File "C:\Users\9821390Z.COMMUN\AppData\Local\pypoetry\Cache\virtualenvs\optimisation-KWHapjG2-py3.9\lib\site-packages\mkdocstrings\extension.py", line 185, in _process_block
                warn(
INFO     -  DeprecationWarning: Parameter `only_exported` is deprecated, use `implicit` instead.
              File "C:\Users\9821390Z.COMMUN\AppData\Local\pypoetry\Cache\virtualenvs\optimisation-KWHapjG2-py3.9\lib\site-packages\mkdocstrings_handlers\python\handler.py", line 195, in collect
                unresolved, iterations = loader.resolve_aliases(only_exported=True, only_known_modules=True)
              File "C:\Users\9821390Z.COMMUN\AppData\Local\pypoetry\Cache\virtualenvs\optimisation-KWHapjG2-py3.9\lib\site-packages\griffe\loader.py", line 181, in resolve_aliases
                warn(
INFO     -  DeprecationWarning: Parameter `only_known_modules` is deprecated, use `external` instead.
              File "C:\Users\9821390Z.COMMUN\AppData\Local\pypoetry\Cache\virtualenvs\optimisation-KWHapjG2-py3.9\lib\site-packages\mkdocstrings_handlers\python\handler.py", line 195, in collect
                unresolved, iterations = loader.resolve_aliases(only_exported=True, only_known_modules=True)
              File "C:\Users\9821390Z.COMMUN\AppData\Local\pypoetry\Cache\virtualenvs\optimisation-KWHapjG2-py3.9\lib\site-packages\griffe\loader.py", line 189, in resolve_aliases
                warn(
ERROR    -  mkdocstrings: modelling.constraints could not be found
ERROR    -  Error reading page 'reference.md':
ERROR    -  Could not collect 'modelling.constraints'

It works if I replace reference.md by ::: modelling but returns only private functions __cached__, __file__, __package__...
This is just making me sure that modelling is a python package, but I can't get what's inside it.

Furthermore, I'm comparing it with another project for which mkdocs serve works well, so I'm quite confused.

Thanks for your help.

Tony Peng · Answer 1 · 2023-02-02T19:05:14.883

I also encounter a similar problem with a python project. mkdocs serve only works for the python files in a few of the project folders but does not work for the python files in some of the other folders (ERROR - Could not collect ...).

I copy a python file from a folder that does not work to a folder that works and then this file can be successfully collected by running mkdocs serve.

In my case, it is discovered that the folders that work all have a __init__.py file that identifies them as regular package folders.

My problem is resolved by adding a __init__.py file to a folder from which we want mkdocs serve to collect files and making it a regular package folder.

Hope this helps in your case!

Mkdocs unable to find modules

1 Answers1