Getting started

[ariG23498]

@NiklasRosenstein In the getting started page under the CLI usage section the code is as follows

$ pydoc-markdown -m my_module --render-toc > my_module.md

I thought this might be helpful to instruct the users to mention the absolute path to the module that they want to render. I suggest this code to be changed to:

$ pydoc-markdown -m absolute/path/to/my_module --render-toc > my_module.md

[NiklasRosenstein]

Hey @ariG23498,

I'll check this out more closely later, but I'm surprised that you are suggesting this because that was not the intended behaviour. The -m option is passed to PythonLoader.modules, which in turn uses docspec_python.load_python_modules(), which in turn uses find_module() which searches the module in the a list of search paths.

https://github.com/NiklasRosenstein/docspec/blob/fb8069fbc3d266b8e5046fe3a728b4db8a7db1bd/docspec-python/src/docspec_python/__init__.py#L68-L73

Maybe this is a side-effect of find_modules() allows slashes in the module_name. The correct way would be to use

$ pydoc-markdown -I absolute/path/to -m my_module --render_toc > my_module.md

[ariG23498]

Hi @NiklasRosenstein I did know about the dependencies of the moudles and the working that -m would do.

I am currently working in a directory that has a sinlge module run.py

Upon exectuing this command $ pydoc-markdown -m run --render-toc > my_module.md The stack trace is as follows

Traceback (most recent call last):
File "/home/aritra/anaconda3/envs/pydoc/bin/pydoc-markdown", line 8, in <module>
sys.exit(cli())
File "/home/aritra/anaconda3/envs/pydoc/lib/python3.8/site-packages/click/core.py", line 829, in __call__
return self.main(*args, **kwargs)
File "/home/aritra/anaconda3/envs/pydoc/lib/python3.8/site-packages/click/core.py", line 782, in main
rv = self.invoke(ctx)
File "/home/aritra/anaconda3/envs/pydoc/lib/python3.8/site-packages/click/core.py", line 1066, in invoke
return ctx.invoke(self.callback, **ctx.params)
File "/home/aritra/anaconda3/envs/pydoc/lib/python3.8/site-packages/click/core.py", line 610, in invoke
return callback(*args, **kwargs)
File "/home/aritra/anaconda3/envs/pydoc/lib/python3.8/site-packages/pydoc_markdown/main.py", line 337, in cli
session.render(pydocmd)
File "/home/aritra/anaconda3/envs/pydoc/lib/python3.8/site-packages/pydoc_markdown/main.py", line 134, in render
modules = config.load_modules()
File "/home/aritra/anaconda3/envs/pydoc/lib/python3.8/site-packages/pydoc_markdown/__init__.py", line 135, in load_modules
modules.extend(loader.load())
File "/home/aritra/anaconda3/envs/pydoc/lib/python3.8/site-packages/docspec_python/__init__.py", line 70, in load_python_modules
files.append((module_name, find_module(module_name, search_path)))
File "/home/aritra/anaconda3/envs/pydoc/lib/python3.8/site-packages/docspec_python/__init__.py", line 134, in find_module
raise ImportError(module_name)
ImportError: run

If I tweak the command to this pydoc-markdown -m absolute/path/run --render-toc > my_module.md It works like a charm!

[NiklasRosenstein]

@ariG23498 You say that run.py is in your current directory, right? Could you try running the below please?

$ pydoc-markdown -I . -m run --render-toc > my_module.md

Thanks

[ariG23498]

@NiklasRosenstein This works :man_dancing: Close the issue as per your needs.

[NumesSanguis]

I was running into this issue as well. I have the following directory (Ubuntu 18.04):

| project
  |- src
    |- library_name
      |- foo.py

No matter in which directory I was or what I tried, I was getting an ImportError

What solved it in the end for me was the -I statement I found here:

pydoc-markdown -I src/library_name -m foo --render-toc > docs/foo.md

So I think it would be useful for other noobs like me if this path -I argument is added to the docs.

[NiklasRosenstein]

hey @NumesSanguis , I'll look into adding the -I option to the docs.

For your example, wouldn't you rather want to go with

pydoc-markdown -I src -m library_name.foo --render-toc > docs/foo.md

?