NiklasRosenstein / pydoc-markdown

Create Python API documentation in Markdown format.
http://niklasrosenstein.github.io/pydoc-markdown/
Other
462 stars 105 forks source link

Custom loader does not get picked up from project directory #70

Closed pief closed 4 years ago

pief commented 5 years ago

I'm trying to use pydocmd in combination with a Django project. Because pydocmd appears to Python import the files it processes, this requires a special loader class that does the Django-specific setup. So I tried a pydocmd.yml configuration such as

loader: "myloader.DjangoPythonLoader"

but then, when calling pydocmd build from within the top-level project directory where I have both pydocmd.yml as well as my myloader.py I get an import exception:

  File "/home/pief/env/lib/python2.7/site-packages/pydocmd/imp.py", line 36, in import_module
    return __import__(name, fromlist=[''])
ImportError: No module named myloader

Upon examining imp.py I noticed that this happens because my project directory is not part of sys.path, presumably due to the way pydocmd calls __main__.py.

If not like this, what is the intended way to configure a project-specific loader?

NiklasRosenstein commented 5 years ago

Hi @pief,

for now, setting PYTHONPATH=".:$PYTHONPATH" should do.

I will take this into consideration for Pydoc-Markdown v3, even if it's not quite as applicable (there will still be cases where a custom implementation of something may be used, but in this particular case it does not require a new loader class).

NiklasRosenstein commented 4 years ago

This is no longer applicable in Pydoc-Markdown 3. Since I won't be doing any feature work on the 2.x version anymore, I'm going to close this out.

casperdcl commented 4 years ago

@NiklasRosenstein what's the v3 way to implement a custom processor (e.g. inherit from pydoc_markdown.contrib.processors.pydocmd.PydocmdProcessor in some file somewhere?)

NiklasRosenstein commented 4 years ago

Hey @casperdcl ,

Currently all plugins need to be registered as a Python entrypoint.

Example:

https://github.com/NiklasRosenstein/pydoc-markdown/blob/ad365888a6ba00313e19e7b9bb34797870861ea0/pydoc-markdown/package.yaml#L51-L63

Afaik entrypoints can only be registered via a setup script. If that doesn't fit in your workflow now, we could maybe add a command-line option or additionally support resolving plugins by their FQN additionally to the entrypoint name. Please do open a new issue in that case though :)