Package: miko
miko(originally:zero)A new Python documentation styleSee how to use a Python object at a glance!Getting StartedThese instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.PrerequisitesPythonYou will need Python 3 to use this module# vermin outputMinimumrequiredversions:3.6
Incompatibleversions:2InstallingOption 1: From PyPIpipinstall--upgrademikoOption 2: From Gitpipinstall--upgradegit+https://github.com/Animenosekai/mikoYou can check if you successfully installed it by printing out its version:$python-c"import miko; print(miko.__version__)"# output:mikov1.1$miko--version# output:mikov1.0PurposeThis new style aims at bringing an ease of use for both humans and computers.It also helps me get concise while writing docstrings as I tend to use different styles even within a same file.StyleMiko defines a new way of documenting your source code.You will here learn the different sections of your documentation string.OutlineTheMikoway of documenting stuff is by using Markdown in your documentation and following the rules below.StartWhen you want to document the object, you need to start the docstring with 3 quotation marks, preferably double quotation marks.You also need to add a line break and pad the whole documentation to line up with the start of the object name.Example: we are using 3 double quotation marks, and we start where the object name starts after a line break.deffunc():"""It needs to start hereHere we continue the documentation string^^^^(do not use this space)"""passEndThe documentation string ends when 3 quotation marks (the same as the beginning ones) are added after the padding.DescriptionAfter starting the documentation string, you can add a description for your object as a normal string.There is not much styling or rules to follow since all the content outside any section is considered part of the description.Example: We are giving a description of the function at the start, but also at the end.deffunc():"""Hello, this is a description.Returns----------boolThe result of the function.But this is also part of the description."""ParametersYou can define what are the different parameters/arguments the callable object is taking.To start explaining the different parameters, you need to use theParameterssection name, followed by a line-break and at least 3 hyphens.A single parameter element is defined by a name, followed by some options. And, on a new line, with a left padding, its description.Exampledeffunc(a,b:int,c=""):"""Parameters----------a: boolthis is the first argumentb: int | float, default = 1.2this is the second argumentc: str, optionalthis is the third argumentit can have multiple lines"""Aliases:Parameters,Parameter,Params,Parm,Arguments,Argument,Args,ArgThe optionsYou can specify options for each parameter.The options are separated from the parameter name using a colon and a space.Each option is separated by a comma.<type>: defines the type of the parameter.optional: defines a parameter as being optional, without needing to specify its default value.(useful with keyword arguments for instance)default: defines a parameter as being optional, by giving it a default value.deprecated: when a parameter is deprecated.TypesTypes can be defined by giving the element class name ordot notationpath.Example:str,translatepy.language.LanguageYou can specify multiple types using the vertical bar separator.Example:int | floatDefaultYou can define a default value using an equal sign.Example:default = 1,default=TrueReturned ValueYou can define what are the values returned by a callable object using theReturnssection.Each returning element is explained with the following rules: the type of the value and a description with a left-padding on a new line.Exampledeffunc():"""Returns-------intthe number returnedstrif it is a string returnedlist[int, str]if it's a list of bothtranslatepy.Languageusing dot notation"""Aliases:Returns,Return,ReturningExampleYou can give examples of your code, writing them as you would in a Python REPL.deffunc(a=False):"""Example------->>> func()"It is false">>> func(True)"It is true"# when using something other than a boolean>>> func(1)2"""You can use# commentsto explain your example.Aliases:Examples,ExampleExceptionsYou can inform the users about any exception/error your callable might be raising using theRaisingsection.Like theReturnssection, you need to give the name of the exception and then a description of why it would raise this exception and the special attribute the exception might have on a new line, left-padded.Exampledeffunc():"""Raises------ValueErrorIf there is an error with the value"""Aliases:Raises,Raise,Raising,Exceptions,Exception,Errors,ErrorWarningsYou can give warnings to the user using theWarningtag.You just need to putWarning, followed by a colon, a space and the warning itself.Exampledeffunc():"""Warning: This is a serious warning...description...Warning: Another warning"""Aliases:Warnings,WarningNoteWarnings are part of the descriptionNotesIf you only want to notify the user about something, you can use theNotetag.You just need to putNote, followed by a colon, a space and the note itself.Exampledeffunc():"""Note: Yup, that's true...description...Note: Another note"""Aliases:Notes,Note,See Also,InformationNoteNotes are part of the descriptionChange logYou can inform the users about how the object got modified over time using theChangelogsection.Like theReturnssection, you need to give the name of the version it got changed on and then a description of how it changed on a new line, left-padded.Exampledeffunc():"""Changelog---------1.4New default string0.6Raises ImportError instead of RuntimeError"""Aliases:Changelog,ChangesDeprecation NoticeTo add a deprecation notice to your object, you can add! DEPRECATED !at the beginning of the docstring.It must be the first thing (aside from whitespace) of the docstring.Example: At the very beginning of the docstringdeffunc():"""! DEPRECATED !This is a cool function.Changelog---------1.5Added a deprecation notice, with the intention of the function being removed on the next major version."""Example: With a slight variationdeffunc():"""!DEPRECATED!This is a cool function."""Aliases:Deprecated,Deprecation,Deprecate,Deprecation NoticeCopyrightYou can add copyright/authors of the code using theCopyrightsection.Like theReturnssection, you need to give the name of the author and then a description of what they did on a new line, left-padded. The description could include stuff like the year they worked on the code, what they did, etc.Exampledeffunc():"""Copyright---------AnimenosekaiThe initial authorSome other devA very cool collaborator"""Aliases:Copyrights,Copyright,Authors,AuthorUsageHere, there will be the Python API Reference.On PythonTwo objects are exposed through the Python APITheDocsobjectYou can use theDocsobject by passing a docstring and an optional function signature.ExamplefrommikoimportDocsparsed=Docs("""HelloNote: this is a testChangelog---------1.0Adding this docstring""")ParametersNameDescriptionTypeDefaultdocsThis is the docstring to parsestr``signatureThe function signature to get the additional parameters frominspect.SignatureNonenoselfIf you don't want to use theselfparameter from the signature, useful for class methodsboolFalseAttributesdescriptionstrThe description of the object in the docstring.parametersList[Parameter]This contains the different parameters found on the function and on the docstringThe attribute returns aListobject withParameterobjects.AParameterobject has the following attributes:AttributeDescriptionTypenameThe name of the parameterstrcontentA list of strings, each one being a line of the parameter descriptionlist[str]deprecatedIf the parameter is deprecatedbooloptionalIf the parameter is optionalbooldefaultThe default value for the parameter, if it has anystr, AnytypesA list of types the parameter can belist[str, Any]returnsraiseschangelogcopyrightList[ListElement]They all share the same schema, aListobject withListElementobjects.AListElementobject has the following attributes:AttributeDescriptionTypenameThe name of the elementstrcontentA list of strings, each one being a line of the element descriptionlist[str]exampleExampleTheexampleattribute contains any example code the docstring might contain.warningsnoteslist[str]Thewarningsandnotesattributes are just a list of warnings or notes it could have find in the description.deprecatedboolIf the object is marked as deprecatedMethodsdumpsThis function lets you dump the documentation string to the cleanest format possible, using all of the information the currentDocshas.The optionalindentparameter (which defaults to 4), lets you choose the indentation level of the output.It returns a string with the output documentation string.as_dictTheas_dictfunction lets you convert theDocsobject to a dictionary.It takes an optionalcamelCaseparameter (which defaults to False), which lets you have a camelCased and JSON friendly dictionary returned.TheFunctionobjectTheFunctionobject lets you get information about a function.On top of the docs, it also lets you retrieve easily its source code filename, line number, name, the different local variables, the parameters, the return annotation, and its name.Using the CLIMikoalso has a CLI, which you can use to get information about a docstring or clean a docstring.🧃❯miko-husage:miko[-h][--version]{info,clean}...SeehowtouseaPythonobjectataglance!positionalarguments:{info,clean}ActionsinfoRetrieveinfoonthegivendocstringcleanCleanthedocstringoptionalarguments:-h,--helpshowthishelpmessageandexit--version,-vshowprogram'sversionnumberandexitmiko infoYou can get information about the docstring usingmiko info.ArgumentsNameAliasesDescriptionTypeDefault--text-tThe docstring to parsestr``--file-fThe file to parsePath(str)``--indent-iThe indentation for the JSON resultint4--noself``Ignoring the "self" parameter from signatures. (useful for class methods)(flag)FalseIt will return information about the given docstring (if--textis given) or a list of information about the different docstrings found in the given file (if--fileis given).It prints a JSON string.miko cleanYou can clean a docstring usingmiko clean.ArgumentsNameAliasesDescriptionTypeDefault--text-tThe docstring to cleanstr``--file-fThe file to cleanPath(str)``--indent-iThe indentation for the cleaned resultint4--noself``Ignoring the "self" parameter from signatures. (useful for class methods)(flag)False--output-oThe file to output the cleaned result toPath(str)NoneIt will clean the given docstring (if--textis given) or it will return the file with the docstrings cleaned (if--fileis given).It prints the cleaned output.Using the VS Code ExtensionYou can also use theMikoextension for Visual Studio Code.It lets you format your files instantly using the command palette.You can add the--noselfflag using theNoselfsetting in the Settings (UI) or themiko-docs.noselfsettings (JSON).Installing the extensionGo tohttps://marketplace.visualstudio.com/items?itemName=Animenosekai.miko-docsto download the published version from the marketplace.You can also use the.vsixfile to install the extension.Head to theextension folderand download the.vsixfile.Then, go to theExtensionssection in VS Code, click on the three dots and selectInstall from VSIX...DeploymentThis module is currently in development and might contain bugs.Feel free to use it in production if you feel like it is suitable for your production even if you may encounter issues.ContributingPull requests are welcome. For major changes, please open a discussion first to discuss what you would like to change.Please make sure to update the tests as appropriate.AuthorsAnime no Sekai-Initial work-AnimenosekaiLicenseThis project is licensed under the MIT License - see theLICENSEfile for details.