search

mitmproxy / pdoc

API Documentation for Python Projects
https://pdoc.dev
MIT No Attribution
1.93k stars 190 forks source link

Using Pdoc with PyO3 #707

Closed shner-elmo closed 2 months ago

shner-elmo commented 3 months ago

Problem Description

Hey, so I'm trying to generate the docs for a PyO3 library, but idk how to include the README to the generated docs.

Usually I insert this in the __init__.py:

"""
.. include:: ../README.md
"""

But in this case I haven't defined the __init__.py, how can I include it? (using the flashtext2.pyi stub file)

System Information

pdoc: 14.5.1 Python: 3.11.4 Platform: Linux-6.5.0-41-generic-x86_64-with-glibc2.35

mhils commented 3 months ago

One option is to put it in the docstring of your module like this:

/// .. include:: ../README.md
#[pymodule]
pub fn your_module(py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
    // ...
}

I don't know if relative paths work as expected, but generally speaking this is how it should work.

shner-elmo commented 3 months ago

Unfortunately that dosent work: 

Warn: Cannot include '../README.MD': [Errno 2] No such file or directory: '/home/shneor/Desktop/projects/python/personal/FlashText2.0/.venv/lib/python3.11/site-packages/flashtext2/../README.MD' (/home/shneor/Desktop/projects/python/personal/FlashText2.0/.venv/lib/python3.11/site-packages/pdoc/docstrings.py:413)

As the README isn't included here: image

Is there any other way I could do it?

mhils commented 3 months ago

You need to either include the README, or fiddle with the relative path. I'd suggest the former. :)

shner-elmo commented 3 months ago

How can I include it?

mhils commented 3 months ago

That's a Python packaging question, not a pdoc question.

(It depends on how you package - most things have some ways to include arbitrary artifacts)

On Wed, Jul 3, 2024, 19:34 Shneor E. @.***> wrote:

How can I include it?

— Reply to this email directly, view it on GitHub https://github.com/mitmproxy/pdoc/issues/707#issuecomment-2206871781, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAHY2PR44WF5MWYLN6EJ66LZKQYZVAVCNFSM6AAAAABKJ5SB2KVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEMBWHA3TCNZYGE . You are receiving this because you commented.Message ID: @.***>