search

datalad / datalad-extension-template

Minimal implementation of a DataLad extension module
http://datalad.org
Other
2 stars 17 forks source link

Generating examples for docs not as easy as template suggests #33

Closed mslw closed 2 years ago

mslw commented 2 years ago

I discovered this issue when building docs for datalad-neuroimaging, which has some examples that need to be converted into ReST.

I understand that the purpose of this code below is to execute BuildManPage and BuildRSTExamplesFromScripts from _datalad_buildsupport submodule.

https://github.com/datalad/datalad-extension-template/blob/0d19eeda18bb83be26564d08af6f91adc9268ad2/docs/source/conf.py#L34-L50

However, when both are needed, they cannot be executed in the loop above by simply uncommenting the for statement, because they have different inputs (user options): BuildManPage has four (manpath, rstpath, parser, cmdsuite) and BuildRSTExamplesFromScripts has two (expath, rstpath), and only one in common.

In the above form, the build failed quietly on BuildRSTExamplesFromScripts (printing "error: option --cmdsuite not recognized" but continuing) and then crashed when rst files were missing.

There might be a prettier way to present it (maybe using subprocess.call or .run and a list of arguments instead of formatted string, although I'm not sure if it's fully compatible), but my workaround was to split it up like so. The template would then need to block-comment the examples part to suggest that it's optional.

mih commented 2 years ago

TBH, I mainly left it in, because it was low priority. It could very well be that the -neuroimaging extension is the last one to carry such examples. I think we have largely abandoned them as means of documentation after the handbook became available. Maybe a sufficient fix is to rip it out.

mslw commented 2 years ago

My initial idea was to add the examples bit as a commented out block.

If ripping the examples out, then probably the BuildRSTExamplesFromScripts class would also have to go, to remove dead ends from the code?

I can do either, and I agree it's not a high priority thing (nor a big quality improvement), it's just that this bit behaving differently threw me off when copying it onto -neuroimaging. So a possibility to make the boilerplate code a bit smaller / more transparent.