main_example.md

Main Example

This is a module docstring. It will appear in documentation.

• Main Example
  • Notes
  • MyClass
    • MyClass().bool
    • MyClass.do_something
  • hello

Notes

You can use Markdown here to make it nicer. Also, in any docstring you can put a global object import string in backticks, like other_module.OtherClass, and it will be transformed to a link.

Handsdown API Index / Examples / Main Example

Auto-generated documentation for examples.main_example module.

Attributes

• MODULE_NAME - This is a comment-style documented global variable, so it is added to main_example module attributes with this comment as a documentation for it: 'My Module'

MyClass

Show source in main_example.py:54

Attributes

• STUFF_COUNT - This is a comment-style documented class attribute, so it is added to main_example.MyClass attributes with this comment as a documentation for it.: 3

MyClass documentation here.

Notes

This time we use RST docstrings format.

Signature

class MyClass(BaseClass): ...

MyClass().bool

Show source in main_example.py:92

Magic methods are added to docs only if they have docstrings.

Returns

True if STUFF_COUNT is not zero

Signature

def __bool__(self) -> bool: ...

MyClass.do_something

Show source in main_example.py:65

This is a public method that uses comment-style type annotations. If decorators or types from annotations are from your project, links to them will be added to See also section. Since this function depends on STUFF_COUNT, we can add it to a docstring in backticks and it will be transformed to a link.

# usage example
def my_stuff(amount):
    return amount > 5

MyClass.do_something(my_stuff)  # False

Notes

Added in version 1.3

Deprecated in version 1.8

Changed in version 1.4 All these directives are added to Notes section and formatted in Sphinx-style.

Arguments

• stuff - Function do execute.

Returns

stuff result.

Signature

@classmethod
def do_something(cls, stuff: StuffCallable) -> bool: ...

hello

Show source in main_example.py:27

This is module function and it is added to documentation even if it does not have a docstring. Function signature will be also generated respecting regular and comment-style type annotations. Let's use PEP 257 format here.

Examples

# Google-style code block here, but we could use Markdown code block as well
>>> hello('John')
'Hello, John!'

>>> hello('')
'Hello!'

Arguments

• name - Name of the person to greet.

Returns

A greeting. No need to put types here if you use type annotations.

Signature

def hello(name: str) -> str: ...