List of all variables and variable labels for codebook?

[HeatherUrry]

Hello! I'd like to create a codebook for a dataset processed with several NK routines. Some of the routines generate many variables. The documentation is generally great at describing the variables, but this information is spread across multiple pages and isn't in machine-readable format. Do you have a list of variables and variable labels you could make available as a resource? (I looked on the documentation website and looked for posts in the Discussions and Issues forums about codebook/code book but didn't find anything; sorry if I missed it.)

[DerAndereJohannes]

We could probably make it such that the documentation builder creates a codebook file using custom sphinx directives. As far as I have understood, there is no standard universal format for codebooks so it would also be important to come up with a format suitable for the library.

[HeatherUrry]

That would be great. A simple two-column csv with variable names in one column and variable labels in the other would work for most purposes.

[DominiqueMakowski]

Would like to see more details and descriptions indeed, even a table in the documentation, but so far the main limitation is that it quite some effort to create and maintain it (especially when it was less stable and we were changing things around) :)

[DerAndereJohannes]

I think we can come up with a nice system like creating a sphinx directive e.g., addtocodebook which would look something like this in the docstring of each x_process function e.g., ecg_process:

.. addtocodebook::
    ECG_Raw,The raw ECG signal
    ECG_Clean,The cleaned ECG signal
    ECG_Rate,Heart rate interpolated between R-peaks
    ...

addtocodebook would simply append all of the info into a csv file (maybe we can also add a column for unit).

And then use the event based API of sphinx after it has finished the build (probably the build-finished event, I would have to look at this again) and use that to add the csv table to a "Codebook" page with also a button to download it.

For developers, this would mean that whenever you change something in the x_process functions, when changing the return output in the documentation, they would also have to reflect these changes in the new addtocodebook directive which we can put directly below the return function too.

This shouldn't be too difficult to produce and maintain either. Let me know your thoughts, I would happily take a look at this.

EDIT: Just realized, instead of having to write it twice, the directive could as well as adding to the csv also write into the rst in the bullet point format that exists right now i.e., * ``"<variable name>"``: <Variable description>, so the information would only have to be present once.

[HeatherUrry]

For the codebook I needed to create this week, I created this file by copying/pasting descriptions from the NK documentation. Figured I'd share in case it's helpful. It only contains info for the variables I generated for one specific study so it's definitely not exhaustive.

[DerAndereJohannes]

Thank you for your sample codebook! I'll take a look at this further soon.