Raw markdown appears in the documentation

[szhorvat]

There is some raw markdown appearing in the python-igraph documentation. Examples:

• https://igraph.org/python/api/latest/igraph.Graph.html#DataFrame
• https://igraph.org/python/api/latest/igraph.Graph.html#get_edge_dataframe

Notice words delimited with * or `, e.g.

These indicate the vertex *names* rather than ids unless `use_vids` is True and these are nonnegative integers.

[ntamas]

It's not Markdown, it's reStructuredText ;)

Putting jokes aside, this is a bit of a mess. When I started python-igraph, there weren't really any documentation standards in the Python community. There were a multitude of competing solutions, one of which was Epydoc, which I chose for writing the docstrings. Epydoc is now defunct, and the only Python documentation generation tool that I know about that supports Epydoc is PyDoctor, so we use that for generating the HTML pages.

In the meanwhile, 15 years have passed and most of the code I write uses in other projects uses reStructuredText markup in the Google docstring style (see here). This is nice and human-readable even when not rendered into HTML (opposed to the @param style that Epydoc uses), so I constantly need to force myself to switch back to thinking/writing in Epydoc when I write igraph docstrings. Sometimes I fail to do so and then you see reStructuredText markup in the docs here and there :)

The long-term sustainable solution would be to rewrite all docstrings in reST + Google style because that seems to be the norm now.

[Yaminyam]

Hello! While looking for an issue with the new field in the api documentation, I found out that the issue was a pydoc issue. (https://github.com/twisted/pydoctor/issues/456) I came across this issue while looking for related information to resolve the issue. If so, are you working on converting the docstring to rest+google right now? If not, is it okay if I try to work on it?

[ntamas]

We are not working on it yet so if you are willing to take up the task, that's great! I would propose that you should fork off your own branch from the develop branch and work on that branch separately.

Note that many docstrings are not in the Python codebase but in the C part, in src/_igraph/*.c, near the end of the file, so in order to gauge how big a task this is, you should also look in the *.c files.

In general I wouldn't bother with describing the types of arguments in the Google-style docstrings because there is a separate issue about adding type annotations to the Python interface in general, and these will be used in the long run.

[tristanlatr]

You can bulk-convert epytext docstring to restructured text with the following software: https://github.com/tristanlatr/epytext2rst

Also, know that pydcotor support multiple types of docstring in different modules. So if you want, you can write some modules with google-style docstring and add __docformat__ = "google" as a module variable and it will be recognized and parsed adequately.

EDIT: That does not work for C extensions, though. But might not be too complicated to make it work.

I'm not sure if this issue has anything to do with twisted/pydoctor#456 honestly.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 14 days if no further activity occurs. Thank you for your contributions.

[iosonofabio]

I'm happy to take it, but have not quite understood what the scope is. If it's about changing those two examples, that's easy. If it's about refactoring our entire docs into google-style docstrings, I don't think I have time for that before day X...

[ntamas]

@iosonofabio I think that we should try to keep the scope limited; let's find all usages of backticks in the docstrings and check how many of those are in files that otherwise use Epytext. These are the places that we should fix. For files that already use reStructuredText, we could simply stick __docformat__ = "restructuredtext en" to the top of the file.