You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Hi @jelly, I'm never going to object to more/better documentation! I can't say I'm very familiar with the standard Python documentation conventions, but we do have an open issue to convert our existing manpages to Markdown (see issue #83). I bring this up because it would be very nice to have our documentation (both manpages and Python docs) written in the same language.
It looks like Sphinx uses reStructuredText, yes? Does it support Markdown?
If so, I think that is fine, but we might want adjust our goals for the manpages from Markdown to reStructuredText as a result.
Usually the documentation is written with sphinx which can output html, and more formats. I am not to experienced with setting it up so I'll have to do some further research on what is possible and maintainable. (If I recall correctly sphinx can even determine on runtime which functions/constants a module has)
Thanks everyone for continuing to look into this, I really appreciate the help!
@drakenclimber and I are busy trying to get the v2.5.0 release out the door, once we finish with that we can start taking a close look at this. Thanks for your patience!
It looks like Sphinx uses reStructuredText, yes? Does it support Markdown?
I've already converted the man pages to markdown, but if needed they can easily be converted to reStructuredText.
FWIW Sphinx has supported Markdown for a few years (though MyST and markdown-it). It obviously doesn't give access to the best goodies like autodoc and domains1, but since the seccomp bindings use cython that probably doesn't matter too much.
Footnotes
not entirely true, MyST provides role and directive extensions to markdown ↩
In an effort to get v2.6.0 out sooner than later, I'm going to suggest we push this out to v2.7.0; if you have any concerns or objections please drop a comment.
Activity
[-]provide python binding documentation[/-][+]RFE: provide python binding documentation[/+]pcmoore commentedon Nov 11, 2019
Hi @jelly, I'm never going to object to more/better documentation! I can't say I'm very familiar with the standard Python documentation conventions, but we do have an open issue to convert our existing manpages to Markdown (see issue #83). I bring this up because it would be very nice to have our documentation (both manpages and Python docs) written in the same language.
It looks like Sphinx uses reStructuredText, yes? Does it support Markdown?
If so, I think that is fine, but we might want adjust our goals for the manpages from Markdown to reStructuredText as a result.
jelly commentedon Nov 12, 2019
Usually the documentation is written with sphinx which can output html, and more formats. I am not to experienced with setting it up so I'll have to do some further research on what is possible and maintainable. (If I recall correctly sphinx can even determine on runtime which functions/constants a module has)
pcmoore commentedon Nov 12, 2019
If you are willing to work on this @jelly I would really appreciate it; if there is anything we can do to help, please let us know!
oxr463 commentedon Apr 10, 2020
@jelly have you begun working on this yet? If not I will pursue the
pandocoption with markdown.jelly commentedon May 31, 2020
I have a branch here https://github.com/jelly/libseccomp/tree/pydocs but did not follow up
oxr463 commentedon Jun 1, 2020
I've already converted the man pages to markdown, but if needed they can easily be converted to reStructuredText.
jelly commentedon Jun 1, 2020
Cool, it's up to the maintainer to decide what he prefers :)
pcmoore commentedon Jun 6, 2020
Thanks everyone for continuing to look into this, I really appreciate the help!
@drakenclimber and I are busy trying to get the v2.5.0 release out the door, once we finish with that we can start taking a close look at this. Thanks for your patience!
pcmoore commentedon Jun 6, 2020
Related issue: #61
xmo-odoo commentedon Feb 25, 2022
FWIW Sphinx has supported Markdown for a few years (though
MySTandmarkdown-it). It obviously doesn't give access to the best goodies like autodoc and domains1, but since the seccomp bindings use cython that probably doesn't matter too much.Footnotes
not entirely true, MyST provides role and directive extensions to markdown ↩
pcmoore commentedon Jan 7, 2024
In an effort to get v2.6.0 out sooner than later, I'm going to suggest we push this out to v2.7.0; if you have any concerns or objections please drop a comment.