[Bug] D100: Missing docstring in public module

[Kristinita]

1. Summary

In valid py file I get warning D100: Missing docstring in public module.

2. Settings

My pelicanconf.py:

#!/usr/bin/env python
# -*- coding: utf-8 -*- #

import logging
""" logging pelican module.

For disabling warnings:
http://docs.getpelican.com/en/stable/settings.html#logging
"""
import sys
"""sys module.

For download plugins from “plugins” folder.
"""

# That Pelican see plugins from this folder
sys.path.append('plugins')

# ****************************************************************************
# *                                  General                                 *
# ****************************************************************************

AUTHOR = 'Саша Черных'
SITENAME = 'Поиск Кристиниты'
SITEURL = 'http://kristinita.ru'

TIMEZONE = 'Europe/Moscow'
DEFAULT_LANG = 'en'

# ****************************************************************************
# *                                   Feed                                   *
# ****************************************************************************

# Feed generation, perhaps, not desired when developing
FEED_ALL_ATOM = 'feeds/all.atom.xml'
CATEGORY_FEED_ATOM = 'feeds/%s.atom.xml'
TRANSLATION_FEED_ATOM = None
AUTHOR_FEED_ATOM = None
AUTHOR_FEED_RSS = None

# Blogroll
# LINKS = (('Pelican', 'http://getpelican.com/'),
#          ('Python.org', 'http://python.org/'),
#          ('Jinja2', 'http://jinja.pocoo.org/'),
#          ('You can edit those links in your config file', '#'),)

# Social widget
# SOCIAL = (('You can add links in your config file', '#'),
#           ('Another social link', '#'),)


# ****************************************************************************
# *                                 Markdown                                 *
# ****************************************************************************

# Include Markdown extensions
# http://docs.getpelican.com/en/stable/settings.html?highlight=MARKDOWN#basic-settings
# https://pythonhosted.org/Markdown/extensions/#third-party-extensions
MARKDOWN = {
    'extension_configs': {
        # Fenced code blocks
        # https://pythonhosted.org/Markdown/extensions/fenced_code_blocks.html
        'markdown.extensions.fenced_code': {},
    },
    'output_format': 'html5',
}

# ****************************************************************************
# *                                Generation                                *
# ****************************************************************************

# Delete old site before building
DELETE_OUTPUT_DIRECTORY = True

# Do not touch in generation process
OUTPUT_RETENTION = [".git"]

LOAD_CONTENT_CACHE = False

# Uncomment following line if you want document-relative URLs when developing
RELATIVE_URLS = True

# Original format without rendering. If true, md rendering to md,
# not md → html
OUTPUT_SOURCES = False

# ****************************************************************************
# *                                  Plugins                                 *
# ****************************************************************************

PLUGIN_PATHS = ['pelican-plugins']
PLUGINS = ['pagefixer', 'pelican_javascript', 'sitemap', 'section_number']

# Sitemap
# https://github.com/getpelican/pelican-plugins/tree/master/sitemap

SITEMAP = {
    'format': 'xml',
    'priorities': {
        'articles': 0,
        'indexes': 0.5,
        'pages': 1
    },
    'changefreqs': {
        'articles': 'never',
        'indexes': 'weekly',
        'pages': 'always'
    }
}

# Section number
# https://github.com/getpelican/pelican-plugins/tree/master/section_number

SECTION_NUMBER_MAX = 5

# Replacer
# https://github.com/narusemotoki/replacer.git

REPLACES = (
    (u'css\\/personal', u'..\\/css\\/personal'),
)

# ****************************************************************************
# *                                   Paths                                  *
# ****************************************************************************

# Path for site content

PATH = 'content'

# Path for pages
# Don't set “PAGE_PATHS = ['']”! See
# https://github.com/getpelican/pelican/issues/2123

PAGE_PATHS = ['Gingerinas', 'Giologica', 'Life-hacks', 'Sasha-Black',
              'Smert-svobode', 'Sublime-Text']

# Path for articles
# [Hack] That exclude articles, include non-exicting folder.
# «ARTICLE_PATHS = None» — critical error, integer parameter

ARTICLE_PATHS = ['None']

# Non-modified files and folders
# [Hack] The register matters. 404.md & 404.html don't work.

STATIC_PATHS = ['']

# That filename = Slug, not necessary to write slug manually for each article

SLUGIFY_SOURCE = 'basename'

# Extra path metadata
# http://manos.im/blog/static-site-pelican-grunt-travis-github-pages/

PAGE_URL = '{slug}.html'
PAGE_SAVE_AS = PAGE_URL
CATEGORY_URL = 'category/{slug}.html'
CATEGORY_SAVE_AS = CATEGORY_URL
TAG_URL = 'tag/{slug}.html'
TAG_SAVE_AS = TAG_URL
TAGS_SAVE_AS = 'tag/alltags.html'

# ****************************************************************************
# *                                   Other                                  *
# ****************************************************************************

# Theme

THEME = 'themes/sashapelican'

# Pagination — division of articles

DEFAULT_PAGINATION = False

TYPOGRIFY = True

# Disable logging of empty alt attribute, needs “import logging” module

LOG_FILTER = [(logging.WARN, 'Empty alt attribute for image %s in %s')]

3. Steps to reproduce

I reproduce the problem in a version of Sublime Text without plugins and user settings.

I install Flake8Lint → I restart Sublime Text → I open pelicanconf.py.

4. Expected behavior

If I check my file in a terminal:

D:\Kristinita>flake8 -v pelicanconf.py
flake8.plugins.manager    MainProcess    226 INFO     Loading entry-points for "flake8.extension".

flake8.plugins.manager    MainProcess    288 INFO     Loading entry-points for "flake8.listen".
flake8.plugins.manager    MainProcess    288 INFO     Loading entry-points for "flake8.report".
flake8.plugins.manager    MainProcess    290 INFO     Loading plugin "C90" from entry-point.
flake8.plugins.manager    MainProcess    291 INFO     Loading plugin "F" from entry-point.
flake8.plugins.manager    MainProcess    314 INFO     Loading plugin "pycodestyle.blank_lines" from entry-point.
flake8.plugins.manager    MainProcess    320 INFO     Loading plugin "pycodestyle.break_around_binary_operator" from entry-point.
flake8.plugins.manager    MainProcess    320 INFO     Loading plugin "pycodestyle.comparison_negative" from entry-point.
flake8.plugins.manager    MainProcess    320 INFO     Loading plugin "pycodestyle.comparison_to_singleton" from entry-point.
flake8.plugins.manager    MainProcess    320 INFO     Loading plugin "pycodestyle.comparison_type" from entry-point.
flake8.plugins.manager    MainProcess    321 INFO     Loading plugin "pycodestyle.compound_statements" from entry-point.
flake8.plugins.manager    MainProcess    321 INFO     Loading plugin "pycodestyle.continued_indentation" from entry-point.
flake8.plugins.manager    MainProcess    321 INFO     Loading plugin "pycodestyle.explicit_line_join" from entry-point.
flake8.plugins.manager    MainProcess    321 INFO     Loading plugin "pycodestyle.extraneous_whitespace" from entry-point.
flake8.plugins.manager    MainProcess    321 INFO     Loading plugin "pycodestyle.imports_on_separate_lines" from entry-point.
flake8.plugins.manager    MainProcess    322 INFO     Loading plugin "pycodestyle.indentation" from entry-point.
flake8.plugins.manager    MainProcess    324 INFO     Loading plugin "pycodestyle.maximum_line_length" from entry-point.
flake8.plugins.manager    MainProcess    325 INFO     Loading plugin "pycodestyle.missing_whitespace" from entry-point.
flake8.plugins.manager    MainProcess    327 INFO     Loading plugin "pycodestyle.missing_whitespace_after_import_keyword" from entry-point.
flake8.plugins.manager    MainProcess    330 INFO     Loading plugin "pycodestyle.missing_whitespace_around_operator" from entry-point.
flake8.plugins.manager    MainProcess    331 INFO     Loading plugin "pycodestyle.module_imports_on_top_of_file" from entry-point.
flake8.plugins.manager    MainProcess    331 INFO     Loading plugin "pycodestyle.python_3000_backticks" from entry-point.
flake8.plugins.manager    MainProcess    331 INFO     Loading plugin "pycodestyle.python_3000_has_key" from entry-point.
flake8.plugins.manager    MainProcess    331 INFO     Loading plugin "pycodestyle.python_3000_not_equal" from entry-point.
flake8.plugins.manager    MainProcess    331 INFO     Loading plugin "pycodestyle.python_3000_raise_comma" from entry-point.
flake8.plugins.manager    MainProcess    333 INFO     Loading plugin "pycodestyle.tabs_obsolete" from entry-point.
flake8.plugins.manager    MainProcess    333 INFO     Loading plugin "pycodestyle.tabs_or_spaces" from entry-point.
flake8.plugins.manager    MainProcess    333 INFO     Loading plugin "pycodestyle.trailing_blank_lines" from entry-point.
flake8.plugins.manager    MainProcess    333 INFO     Loading plugin "pycodestyle.trailing_whitespace" from entry-point.
flake8.plugins.manager    MainProcess    333 INFO     Loading plugin "pycodestyle.whitespace_around_comma" from entry-point.
flake8.plugins.manager    MainProcess    333 INFO     Loading plugin "pycodestyle.whitespace_around_keywords" from entry-point.
flake8.plugins.manager    MainProcess    334 INFO     Loading plugin "pycodestyle.whitespace_around_named_parameter_equals" from entry-point.
flake8.plugins.manager    MainProcess    334 INFO     Loading plugin "pycodestyle.whitespace_around_operator" from entry-point.
flake8.plugins.manager    MainProcess    334 INFO     Loading plugin "pycodestyle.whitespace_before_comment" from entry-point.
flake8.plugins.manager    MainProcess    334 INFO     Loading plugin "pycodestyle.whitespace_before_parameters" from entry-point.
flake8.plugins.manager    MainProcess    334 INFO     Loading plugin "default" from entry-point.
flake8.plugins.manager    MainProcess    338 INFO     Loading plugin "pylint" from entry-point.
flake8.plugins.manager    MainProcess    343 INFO     Loading plugin "quiet-filename" from entry-point.
flake8.plugins.manager    MainProcess    345 INFO     Loading plugin "quiet-nothing" from entry-point.
flake8.checker            MainProcess    349 WARNING  The --jobs option is not available on Windows due to a bug (https://bugs.python.org/issue27649) in Python 2.7.11+ and 3.3+. We have detected that you are running an unsupported version of Python on Windows. Ignoring --jobs arguments.
flake8.checker            MainProcess    349 INFO     Making checkers
flake8.checker            MainProcess    356 INFO     Checking 1 files
flake8.main.application   MainProcess    400 INFO     Finished running
flake8.main.application   MainProcess    401 INFO     Reporting errors
flake8.main.application   MainProcess    401 INFO     Found a total of 0 violations and reported 0

Also, I don't get a warning, if I use SublimeLinter-flake8 package.

5. Actual behavior

6. Environment

Operating system and version:
Windows 10 Enterprise LTSB 64-bit EN
Sublime Text:
Build 3126
Python:
3.6.1
Flake8:
3.3.0 (mccabe: 0.6.1, pycodestyle: 2.3.1, pyflakes: 1.5.0) CPython 3.6.1 on Windows

Thanks.

[Tagirijus]

+1 I also have this issue (Sublime Text Build 3126 on Linux Mint 17.1) using python 2 code. The package control of sublime told me it's flake8 2.4.3 though.

[Tagirijus]

Okay, I found out how to "solve" this. Seems to be some specification of the formatting of a Python script? This won't work:

# coding=utf-8

print 'Hello world!'

but this:

# coding=utf-8

"""
This is an example script.

It seems that it has to have THIS docstring with a summary line, a blank line
and sume more text like here. Wow.
"""

print 'Hello world!'

So the missing docstring is the comment block with a single line + blank line + text, which seems to be needed so that the warning does not occur with flake8 here.

[leotop]

single line + blank line + text = fix

#!/usr/bin/env python3
# -*- coding: UTF-8 -*-

"""
This is an example script.

It seems that it has to have THIS docstring with a summary line, a blank line
and sume more text like here. Wow.
"""

print("ok")

[HenrikEckermann]

So, is it necessary to put in these first lines in each Python file to avoid this error? Is this a bug or is it actually the wrong style to leave this head out?

[Kristinita]

I remove Flake8Lint and migrate to Anaconda. It supports flake8 linting.

1. at January 2018 Anaconda active maintained, Flake8Lint — not maintained 2 years;
2. in Anaconda I can't get bugs, that described in issues of this repository;
3. if I fix the error in my code, Anaconda faster stops showing error;
4. see comparison Anaconda and SublimeLinter in Anaconda site.

Thanks.

[Tagirijus]

Many thanks for this hint! (=

[mohammedhrima]

go to "settings.json"
and disable python pydocstyle by doing that
it worked for me
"python.linting.pydocstyleEnabled": false