See how to use a Python object at a glance!
Project description
miko
(originally: zero
)
A new Python documentation style
See how to use a Python object at a glance!
Getting Started
These 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.
Prerequisites
Python
You will need Python 3 to use this module
# vermin output
Minimum required versions: 3.6
Incompatible versions: 2
Installing
Option 1: From PyPI
pip install --upgrade miko
Option 2: From Git
pip install --upgrade git+https://github.com/Animenosekai/miko
You can check if you successfully installed it by printing out its version:
$ python -c "import miko; print(miko.__version__)"
# output:
miko v1.1
$ miko --version
# output:
miko v1.0
Purpose
This 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.
Style
Miko defines a new way of documenting your source code.
You will here learn the different sections of your documentation string.
Outline
The Miko way of documenting stuff is by using Markdown in your documentation and following the rules below.
Start
When 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.
def func():
"""
It needs to start here
Here we continue the documentation string
^^^^
(do not use this space)
"""
pass
End
The documentation string ends when 3 quotation marks (the same as the beginning ones) are added after the padding.
Description
After 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.
def func():
"""
Hello, this is a description.
Returns
----------
bool
The result of the function.
But this is also part of the description.
"""
Parameters
You can define what are the different parameters/arguments the callable object is taking.
To start explaining the different parameters, you need to use the Parameters
section 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.
Example
def func(a, b: int, c = ""):
"""
Parameters
----------
a: bool
this is the first argument
b: int | float, default = 1.2
this is the second argument
c: str, optional
this is the third argument
it can have multiple lines
"""
Aliases:
Parameters
,Parameter
,Params
,Parm
,Arguments
,Argument
,Args
,Arg
The options
You 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.
Types
Types can be defined by giving the element class name or dot notation path.
Example:
str
,translatepy.language.Language
You can specify multiple types using the vertical bar separator.
Example:
int | float
Default
You can define a default value using an equal sign.
Example:
default = 1
,default=True
Returned Value
You can define what are the values returned by a callable object using the Returns
section.
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.
Example
def func():
"""
Returns
-------
int
the number returned
str
if it is a string returned
list[int, str]
if it's a list of both
translatepy.Language
using dot notation
"""
Aliases:
Returns
,Return
,Returning
Example
You can give examples of your code, writing them as you would in a Python REPL.
def func(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 # comments
to explain your example.
Aliases:
Examples
,Example
Exceptions
You can inform the users about any exception/error your callable might be raising using the Raising
section.
Like the Returns
section, 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.
Example
def func():
"""
Raises
------
ValueError
If there is an error with the value
"""
Aliases:
Raises
,Raise
,Raising
,Exceptions
,Exception
,Errors
,Error
Warnings
You can give warnings to the user using the Warning
tag.
You just need to put Warning
, followed by a colon, a space and the warning itself.
Example
def func():
"""
Warning: This is a serious warning
...description...
Warning: Another warning
"""
Aliases:
Warnings
,Warning
Note
Warnings are part of the description
Notes
If you only want to notify the user about something, you can use the Note
tag.
You just need to put Note
, followed by a colon, a space and the note itself.
Example
def func():
"""
Note: Yup, that's true
...description...
Note: Another note
"""
Aliases:
Notes
,Note
,See Also
,Information
Note
Notes are part of the description
Change log
You can inform the users about how the object got modified over time using the Changelog
section.
Like the Returns
section, 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.
Example
def func():
"""
Changelog
---------
1.4
New default string
0.6
Raises ImportError instead of RuntimeError
"""
Aliases:
Changelog
,Changes
Deprecation Notice
To 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 docstring
def func():
"""! DEPRECATED !
This is a cool function.
Changelog
---------
1.5
Added a deprecation notice, with the intention of the function being removed on the next major version.
"""
Example: With a slight variation
def func():
"""
!DEPRECATED!
This is a cool function.
"""
Aliases:
Deprecated
,Deprecation
,Deprecate
,Deprecation Notice
Copyright
You can add copyright/authors of the code using the Copyright
section.
Like the Returns
section, 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.
Example
def func():
"""
Copyright
---------
Animenosekai
The initial author
Some other dev
A very cool collaborator
"""
Aliases:
Copyrights
,Copyright
,Authors
,Author
Usage
Here, there will be the Python API Reference.
On Python
Two objects are exposed through the Python API
The Docs
object
You can use the Docs
object by passing a docstring and an optional function signature.
Example
from miko import Docs
parsed = Docs(
"""
Hello
Note: this is a test
Changelog
---------
1.0
Adding this docstring
"""
)
Parameters
Name | Description | Type | Default |
---|---|---|---|
docs |
This is the docstring to parse | str | `` |
signature |
The function signature to get the additional parameters from | inspect.Signature | None |
noself |
If you don't want to use the self parameter from the signature, useful for class methods |
bool | False |
Attributes
description
str
The description of the object in the docstring.
parameters
List[Parameter]
This contains the different parameters found on the function and on the docstring
The attribute returns a List
object with Parameter
objects.
A Parameter
object has the following attributes:
Attribute | Description | Type |
---|---|---|
name |
The name of the parameter | str |
content |
A list of strings, each one being a line of the parameter description | list[str] |
deprecated |
If the parameter is deprecated | bool |
optional |
If the parameter is optional | bool |
default |
The default value for the parameter, if it has any | str, Any |
types |
A list of types the parameter can be | list[str, Any] |
returns
raises
changelog
copyright
List[ListElement]
They all share the same schema, a List
object with ListElement
objects.
A ListElement
object has the following attributes:
Attribute | Description | Type |
---|---|---|
name |
The name of the element | str |
content |
A list of strings, each one being a line of the element description | list[str] |
example
Example
The example
attribute contains any example code the docstring might contain.
warnings
notes
list[str]
The warnings
and notes
attributes are just a list of warnings or notes it could have find in the description.
deprecated
bool
If the object is marked as deprecated
Methods
dumps
This function lets you dump the documentation string to the cleanest format possible, using all of the information the current Docs
has.
The optional indent
parameter (which defaults to 4), lets you choose the indentation level of the output.
It returns a string with the output documentation string.
as_dict
The as_dict
function lets you convert the Docs
object to a dictionary.
It takes an optional camelCase
parameter (which defaults to False), which lets you have a camelCased and JSON friendly dictionary returned.
The Function
object
The Function
object 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 CLI
Miko
also has a CLI, which you can use to get information about a docstring or clean a docstring.
🧃❯ miko -h
usage: miko [-h] [--version] {info,clean} ...
See how to use a Python object at a glance!
positional arguments:
{info,clean} Actions
info Retrieve info on the given docstring
clean Clean the docstring
optional arguments:
-h, --help show this help message and exit
--version, -v show program's version number and exit
miko info
You can get information about the docstring using miko info
.
Arguments
Name | Aliases | Description | Type | Default |
---|---|---|---|---|
--text |
-t |
The docstring to parse | str | `` |
--file |
-f |
The file to parse | Path(str) | `` |
--indent |
-i |
The indentation for the JSON result | int | 4 |
--noself |
`` | Ignoring the "self" parameter from signatures. (useful for class methods) | (flag) | False |
It will return information about the given docstring (if --text
is given) or a list of information about the different docstrings found in the given file (if --file
is given).
It prints a JSON string.
miko clean
You can clean a docstring using miko clean
.
Arguments
Name | Aliases | Description | Type | Default |
---|---|---|---|---|
--text |
-t |
The docstring to clean | str | `` |
--file |
-f |
The file to clean | Path(str) | `` |
--indent |
-i |
The indentation for the cleaned result | int | 4 |
--noself |
`` | Ignoring the "self" parameter from signatures. (useful for class methods) | (flag) | False |
--output |
-o |
The file to output the cleaned result to | Path(str) | None |
It will clean the given docstring (if --text
is given) or it will return the file with the docstrings cleaned (if --file
is given).
It prints the cleaned output.
Using the VS Code Extension
You can also use the Miko
extension for Visual Studio Code.
It lets you format your files instantly using the command palette.
You can add the --noself
flag using the Noself
setting in the Settings (UI) or the miko-docs.noself
settings (JSON).
Installing the extension
Go to https://marketplace.visualstudio.com/items?itemName=Animenosekai.miko-docs to download the published version from the marketplace.
You can also use the .vsix
file to install the extension.
Head to the extension folder and download the .vsix
file.
Then, go to the Extensions section in VS Code, click on the three dots and select Install from VSIX...
Deployment
This 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.
Contributing
Pull 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.
Authors
- Anime no Sekai - Initial work - Animenosekai
License
This project is licensed under the MIT License - see the LICENSE file for details.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.