Improvements to `docs_rendering`
We have a lot of same text module/block in our documentation which store in a large so called lib.utils.DOC_DICT
dictionary and render them using a decorator function called lib.utils.render_docs
. The text block templates can be inserted using a ${key}
statement where key
refers to the template text in the dictionary. Even though this is already very useful and reduces the number of duplications I see currently two possible enhancements:
-
We have some descriptions which are still inserted manually. One example is the method explanation of the
save
method. -
Another thing is that
lib.utils.render_docs
only does a flat rendering of the templates. i.e if you have nested templates only the "top" one will be rendered:
DOC_DICT = {"parameter_outer": "my parameter descriptions using ${inner}",
"inner": "an inner statement",
}
@render_docs
def function():
"""${parameter_outer}"""
...
calling the code results in a docstring of "my parameter descriptions using ${inner}"
. The inner template is not rendered. This makes inheriting of templates very tedious as shown in lib.utils
where we have to stack them by hand. Adding nested replacement will allow us to clean this up a lot. If one implements this the should add a max_depth
indicicating the depth until which templates are replaced to avoid infinite recursion loops.