• Packages
  • Themes
  • Documentation
  • Blog
  • Discussions
Sign in

docblock-python

Inserts documentation blocks for python functions
  • #python
  • #documentation
  • #autocomplete
  • #linter
spadarian
0.19.1 44,842
16
  • Repo
  • Bugs
  • Versions
  • License
Flag as spam or malicious

Python DocBlock Package

Build Status Plugin installs! Package version!

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

Demo

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.

Lint

TODO

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

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

I think this package is bad news.

Good catch. Let us know what about this package looks wrong to you, and we'll investigate right away.

  • Terms of Use
  • Privacy
  • Code of Conduct
  • Releases
  • FAQ
  • Contact
with by