pycco-docs / pycco

Literate-style documentation generator.

Home Page:https://pycco-docs.github.io/pycco/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Source code omitted if indentation level has no comment/docstring

akaihola opened this issue · comments

Consider this Python source snippet:

# Top-level comment
if True:
    class MyClass:
        def mymethod(self):
            if True:
                # Innermost comment
                print "Success"

When run through Pycco, this produces approximately:

nesting.py

Top-level comment     | if True:
                      |
Innermost comment     |                print "Success"

If I want the source code to be displayed correctly, I need to add either a comment or a docstring to every indentation level:

# Top-level comment
if True:
    class MyClass:
        """Docstring for MyClass"""
        def mymethod(self):
            """Docstring for mymethod"""
            # dummy comment for the if clause
            if True:
                # Innermost comment
                print "Success"

Maybe this is by design and is meant to encourage generous use of comments, but for me it feels cumbersome and is a blocker for using Pycco for larger existing codebases.

I'm not sure whether this is by design, but I have noticed this behavior as well. This behavior was introduced by bcb8f2c. Reverting that commit should fix the problem.

At the moment I consider this a bug, as this behavior was not in 0.2.0 and it forcibly hides any sections of code without commenting at every level.

Fixed by #35.