RFE: provide python binding documentation

[jelly]

I was wondering if the project is open to providing python documentation build with sphinx possibly with some examples.

[pcmoore]

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]

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]

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]

@jelly have you begun working on this yet? If not I will pursue the pandoc option with markdown.

[jelly]

I have a branch here https://github.com/jelly/libseccomp/tree/pydocs but did not follow up

[oxr463]

I've already converted the man pages to markdown, but if needed they can easily be converted to reStructuredText.

[jelly]

Cool, it's up to the maintainer to decide what he prefers :)

[pcmoore]

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]

Related issue: https://github.com/seccomp/libseccomp/issues/61

[xmo-odoo]

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 domains[^1], but since the seccomp bindings use cython that probably doesn't matter too much.

[^1]: not entirely true, MyST provides role and directive extensions to markdown

[pcmoore]

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.