search

cmry / markdoc

Convert NumPy-styled Python docstring to Markdown.
MIT License
12 stars 4 forks source link

markdoc doesn't seem to generate any docs for non-class functions #1

Open jwlodek opened 4 years ago

jwlodek commented 4 years ago

Hi, I realize that this repository has not been worked on for several years, but I was wondering if there was a known issue with dealing with non-class based function docstrings.

If it is a known problem, I would like to try my hand at adding support for this use case.

cmry commented 4 years ago

Hi, thanks for your interest! Indeed, it's been quite a while since I worked on this as a small holiday project. You're right, it indeed assumes everything is a class. I guess you could edit the class split (https://github.com/cmry/markdoc/blob/master/markdoc.py#L138) and identify def statements that are not indented, and pipe them through an altered version of the method parser bit (https://github.com/cmry/markdoc/blob/master/markdoc.py#L364).

I do really appreciate the support offer. But, if I'm completely honest, I'd rather advise you to invest your time and energy in getting to grips with a more mature framework for generating online documentation of your code, such as sphinx. I'm confident that will be much more useful for you in the long run! :)

jwlodek commented 4 years ago

Hi, thanks for the response. I actually do primarily use sphinx when I need to make documentation, however, for some of my smaller projects it seems to be somewhat overkill, and I like how markdoc can generate a simple .md file I can include with the repository, rather than have a long pdf document or external website. I usually use this for single file projects, which I often make without the use of classes at all, which is why I discovered that non-class functions weren't being detected.

If I have some free time in the future I may try and add support for this, and if I do I'll be sure to make a pull request. Either way, thanks for this project, I've found it very useful.

cmry commented 4 years ago

Alright, fair enough; also exactly my reason for writing it. Maybe I might also have time in the future to clean up the documentation / work on the known issues etc. and make it a bit more proper overall. In any case, very glad to hear it's been useful!