Request: adding constants template and parsing

[gaffarelj]

To document the tudatpy.constants module, it would be great to have a constant template implemented in multidoc/template.py, and a constant parser in multidoc/parsing/api.py.

[gaffarelj]

@geoffreygarrett would you have time to take care of this?

[gaffarelj]

It seems to me that these are already implemented, but buggy in their current state.
I think that name: str should be added on this line and that this line should be replaced by return constant.dict() to make things work.

[gaffarelj]

Actually just changing these two lines is not enough. Doing so, the generated docstring (docstrings.h) looks like this:

namespace constants {

static inline std::string get_docstring(std::string name, int variant=0) {

    if (name == "test") {
        return "test";


    } else if(name == "SEA_LEVEL_GRAVITATIONAL_ACCELERATION") {
        return {'name': 'SEA_LEVEL_GRAVITATIONAL_ACCELERATION', 'summary': 'Earth sea level gravitational acceleration.', 'extended_summary': None, 'see_also': None, 'references': None, 'examples': None};





    } else {
        return "No documentation found.";
    }

}


}

[gaffarelj]

I am (trying) to take care of this feature. It's underways (I still have to extend the template a little and test a lot).

[geoffreygarrett]

One of the reasons I stumbled on this feature initially, before it was requested (I did try do all of this the first time around) was because constants can't be assigned docstrings in either normal python or pybind11, as far as I know they must both be documented inside the module section itself.

So we have unique entries in the docstrings.h right now, but in fact the constant's documentation should be parsed Into the module docstings. This was a problem because classes and modules (until this point) had the same exact documentation subsections.

You said you were making progress, what direction did you go to solve this?

[gaffarelj]

Well I made progress in producing docstrings associated with the constants (in docstrings.h). I now wish I started from associating generated docstrings to the constants in C++. Indeed, that looks like an issue, for which I have no answer. I will continue investigating this this week.