WIP: Added docgen command #60
Conversation
There was a problem hiding this comment.
This is mostly pretty good, though there are a couple of blockers here, particularly: why the change to load_python.py, and let's have a better description fallback. If you really have to put a "TODO" which I don't agree with for the reasons I've stated (I also think that VarTypes of Base64 and JSON are pretty self-explanatory), then you should at least put the class name in there.
| self.get_repository(can_fail=True) | ||
| objs = load_python.PythonBaseFile.get_kube_objs() | ||
| types = load_python.PythonBaseFile.get_kube_types() | ||
| formats = load_python.PythonBaseFile.get_kube_vartypes() |
There was a problem hiding this comment.
Not sure I particularly like the name "formats" for vartypes.
| header += '# Table of contents\n\n' | ||
|
|
||
| header += '- [Formats](#formats)\n' | ||
| md += '\n# Formats\n\n' |
There was a problem hiding this comment.
This structure makes sense if you add options (which I think you should) for which sections you should generate.
And as mentioned, I think "formats" is an awful name for this.
| for fname in sorted(formats.keys()): | ||
| header += ' - [{}](#{})\n'.format(fname, fname.lower()) | ||
| md += '## {}\n\n'.format(fname) | ||
| md += '{}\n\n'.format(formats[fname].get_description()) |
|
|
||
| with open(os.path.join(r.basepath, 'docs/rubiks.class.md'), 'w') as f: | ||
| f.write(header.encode('utf-8')) | ||
| f.write(md.encode('utf-8')) |
There was a problem hiding this comment.
Again, please fix your editor so that the file ends in a newline and we don't get spurious diffs down the line.
| def get_description(cls): | ||
| if cls.__doc__ is not None and cls.__doc__ is not '': | ||
| return '\n'.join([line.strip() for line in cls.__doc__.split('\n')]) | ||
| return 'TODO: Description is still missing from the class docstring.\nStay tuned to have more hint about this variable.' |
There was a problem hiding this comment.
I don't like this text - after all, Boolean/Integer etc should speak for themselves. I think this should be:
return cls.__name__| @@ -515,6 +537,7 @@ def cluster_info(c): | |||
|
|
|||
| ret.update(self.__class__.get_kube_objs()) | |||
| ret.update(self.__class__.get_kube_vartypes()) | |||
| ret.update(self.__class__.get_kube_types()) | |||
There was a problem hiding this comment.
Why is this needed!? Why do you think you need, say "Integer" or "String" in the DSL?
| if cls.__doc__ is not None and cls.__doc__ is not '': | ||
| return '\n'.join([line.strip() for line in cls.__doc__.split('\n')]) | ||
| return 'TODO: Description is still missing from the class docstring.\nStay tuned to have more hint about this variable.' | ||
|
|
This new command can be used to generate markdown documentation for any rubiks setup.
If run with modules all the objects included into the modules will be automatically added inside the generated markdown.
the markdown will be placed inside
docs/rubiks.class.mdTODO:
unknown transformation)Sections