pdoc3 / pdoc3/pdoc

Module-level docstring section name disrupts parsing of class code

Open
#143 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

upstream
Dominant language
Python
Stars
1.2k
Forks
146
PR merge metrics
No merged PRs in 30d

Description

Expected Behavior

When dealing with docstrings at the module level and the class level, pdoc3 should include the valid source code for the class in the rendered HTML, regardless of what is in module-level docstrings.

Actual Behavior

Including a section name in the module-level docstring that matches the name of a class to be documented causes pdoc3 to fail to parse the source and as a result fail to include it in the rendered HTML.

Steps to Reproduce
  1. Create file min_working_example.py:
"""Module docstring.

Some additional text.

class ABC
---------

This header creates the problem.

class `DEF`
-----------

This header does not create a problem.

"""
from __future__ import absolute_import
from __future__ import unicode_literals


__all__ = ["ABC", "DEF"]


class ABC:
    """ABC class docstring."""

    def __init__(self):
        """Construct object."""
        self.name = "ABC"

class DEF:
    """DEF class docstring."""

    def __init__(self):
        """Construct object."""
        self.name = "DEF"
  1. Run pdoc3 --html min_working_example which yields the following error:
~/.local/lib/python3.6/site-packages/pdoc/__init__.py:227: UserWarning: Couldn't get/parse source of '<Class 'min_working_example.ABC'>'
  warn("Couldn't get/parse source of '{!r}'".format(doc_obj))
Additional info
  • pdoc version: 0.7.2
  • May be related to #134 and #106

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the failure with min_working_example.py using pdoc3 --html min_working_example. Start around the source-parsing warning in pdoc/init.py near line 227 and trace how the module-level class ABC heading affects class source extraction. Done means the rendered HTML includes valid source for ABC regardless of that module docstring section name.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.