Python DocBlock Package

DocBlock is a package for Atom which helps you to document your python code.

Installation

From the command line run apm install docblock-python. You can also install it from the Atom Package manager.

Available styles

• Numpy style: A Guide to NumPy/SciPy Documentation.
• Google style: Google Python Style Guide.
• Sphinx style: Sphinx documentation.
• Epytext style: Epytext documentation.

Project configuration file

It is possible to set configurations for different projects. You just need to add a .docblock.json file to the project root directory including any of the package settings. Below you can see an example JSON with all the settings set to their default value.

{
  "style": "numpy",
  "indent": true,
  "parameters": true,
  "quote_type": "double",
  "default_desc_text": true,
  "use_defaults": true,
  "returns": true,
  "raises": false,
  "examples": false,
  "types": {
    "use_types": true,
    "separate_types": false
  },
  "lint": false
}

You can generate the .docblock.json file by clicking on the Packages -> docblock-python -> Save current settings menu.

A full list of the options and their possible values are described below:

Option	Value	Description
style	"numpy", "google", "sphinx" or "epytext"	Docblock style
indent	true or false	Initial indent
parameters	true or false	Describe parameters
quote_type	"double" or "single"	Type of triple quotes to use
default_desc_text	true or false	Show default description text ("Description of...")
use_defaults	true or false	Add default value to parameter description
returns	true or false	Describe returned value
raises	true or false	Describe raised exceptions
examples	true or false	Should illustrate how to use the function/class (doctest)
types.use_types	true or false	Parameter and attribute type
types.separate_types	true or false	Show types in a different line (sphinx style only)
lint	true or false	Enable lint to show missing documentation (experimental)

Lint support

This experimental feature should show you when the documentation is not up-to-date. At the moment, it only checks if the current parameters and attributes are documented (not if you are documenting something that doesn't exist).

In order to this feature to work, you need to install Linter and enable the option in docblock-python settings.

TODO

This is a non-exhaustive list of future additions. If you have any suggestions, drop me an email.

• Add Google style
• Add Sphinx style
• Scan for Exceptions
• Convert between styles
• Add support for Type Hints (PEP 484)
• Add lint support to show incomplete documentation
• Project configuration file
• Add menu item to write current settings to config file.