Package: py-md-doc
PyMdDocGenerate markdown documentation for your Python scripts' code comments that is compatible with GitHub. It's like Sphinx, but with simpler requirements and results. It's also not as flexible as Sphinx and is mainly useful for scripts containing only a few classes.For example output,see the code documentation for this module.Installationpip3installpy-md-docUsage1. Documentation for this moduleClone this repo.cd path/to/py_md_doc(Replacepath_to) with the actual path to this repo.)python3 doc_gen.py2. Documentation for your own modulefrompy_md_docimportPyMdDocfrompathlibimportPathmd=PyMdDoc(input_directory=Path("my_module/my_module"),files=["my_script.py"],metadata_path="metadata.json")md.get_docs(output_directory=Path("my_module/docs"))For the API,read this.3. Documentation with class inheritanceGenerate documentation for each child script (see above).UseClassInheritanceto append inherited fields, functions, etc. from the generated documents.Code comments formatOne class per file.Class descriptions begin and end with"""immediately after the class definition.Class variables begin with""":class_varand end with"""and must be before the constructor declaration. The line immediately after them is the variable declaration.Fields begin with""":fieldand end with"""in the constructor. The line immediately after them is the field declaration.Function descriptions begin and end with"""immediately after the function definition.Function parameter descriptions are lines within the function description that begin with:paramFunction return description are lines within the function description that begin with:return:Function names that begin with_are ignored.The code for PyMdDoc as well as the code examples below usetype hinting. You donotneed type hinting in your code for PyMdDoc to work properly.classMyClass:"""This is the class description."""""":class_varThis is a class variable."""CLASS_VAR:int=0def__init__(self):"""field:The ID of this object."""self.val=0defset_val(self,val:int)->None:"""Set the val of this object.:param val: The new value."""self.val=valdefget_val(self)->int:""":return The value of this object."""returnself.valdef_private_function(self)->None:"""This won't appear in the documentation."""returnEnum valuesare documented by commenting the line next to them.fromenumimportEnumclassMyEnum(Enum):a=0# The first value.b=1# The second value.Metadata fileYou can add an optional metadata dictionary (seethe constructor).A metadata file is structured like this:{"PyMdDoc":{"Constructor":{"description":"","functions":["__init__"]},"Documentation Generation":{"description":"Use these functions to generate your documentation.","functions":["get_docs","get_doc"]},"Helper Functions":{"description":"These functions are used in `get_docs()`. You generally won't need to call these yourself.","functions":["get_class_description","get_class_variables","get_function_documentation","get_enum_values","get_fields"]}}}The top-order key of the dictionary ("PyMdDoc") is the name of the class. You don't need to add every class that you wish to document. If the class is not listed inmetadata.jsonbut is listed in thefilesparameter, its functions will be documented in the order they appear in the script.Each key in the class metadata ("Constructor","Documentation Generation","Helper Functions") is a section.Each section name will be a header in the document, except for"Constructor"and"Ignore".Any function in the"Ignore"category won't be documented.Each section has a"description"and a list of names of"functions". The functions will appear in the section in the order they appear in this list.If the class name is listed inmetadata.jsonand a function name can't be found in any of the section lists, the console will output a warning. For example, if you were to add a function namednew_function()toPyMdDoc, you'd have to add it to a section in the metadata file as well becausePyMdDocis a key in the metadata dictionary.LimitationsThis script is for class objects only and won't document functions that aren't in classes:defmy_func():"""This function will be ignored."""passclassMyClass:"""This class will be in the documentation."""defclass_func(self):"""This function will be in the documentation."""passdefanother_my_func():"""This function will be erroneously included with MyClass."""passFunctions can be grouped and reordered into categories, but classes and fields are always documented from the top of the document to the bottom:classMyClass:"""This class will documented first."""defclass_func(self):"""This function will be documented first."""passdefanother_class_func(self):"""This function will be documented second."""passclassAnotherClass:"""This class will be documented second."""VarDocTo create API documentation for a script that contains only variables (no classes or functions), useVarDoc.ChangelogSeechangelog.