Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for variable doc-comments starting with '#:' #292

Merged
merged 10 commits into from
Jan 2, 2021

Conversation

csm10495
Copy link
Contributor

@csm10495 csm10495 commented Dec 19, 2020

I'd like to write a unit-test for this functionality, though I'm having some trouble running the existing suite: #291

This basically matches up with sphinx behavior and a similar implementation.

Fixes #289
Resolves #291

@csm10495 csm10495 force-pushed the pound_comments branch 3 times, most recently from 803f7fd to e52311f Compare December 19, 2020 05:43
Copy link
Member

@kernc kernc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks neat! But definitely will need a unit test. 😬

pdoc/__init__.py Outdated Show resolved Hide resolved
pdoc/__init__.py Outdated Show resolved Hide resolved
pdoc/__init__.py Outdated Show resolved Hide resolved
pdoc/__init__.py Outdated Show resolved Hide resolved
pdoc/__init__.py Outdated Show resolved Hide resolved
@kernc kernc changed the title Add support for variable docstrings starting with '#:'. Closes #289 Add support for variable doc-comments starting with '#:' Dec 20, 2020
@csm10495
Copy link
Contributor Author

@kernc, added unit tests, fixed running on Windows. Let me know if it needs other changes. Otherwise feel free to merge.

@csm10495
Copy link
Contributor Author

@kernc let me know if further changes are needed. Thanks!

pdoc/__init__.py Outdated Show resolved Hide resolved
pdoc/test/__init__.py Show resolved Hide resolved
pdoc/test/__init__.py Outdated Show resolved Hide resolved
csm10495 and others added 2 commits December 24, 2020 09:59
Co-authored-by: kernc <kerncece@gmail.com>
@csm10495
Copy link
Contributor Author

@kernc I've made the requested changes. Let me know if it seems ok now. Thanks!

pdoc/test/__init__.py Outdated Show resolved Hide resolved
@kernc
Copy link
Member

kernc commented Dec 26, 2020

Now with this feature in place, amendment of documentation is in order:

pdoc/pdoc/documentation.md

Lines 106 to 137 in 28b366a

### Docstrings for variables
[variable docstrings]: #docstrings-for-variables
Python by itself [doesn't allow docstrings attached to variables][PEP-224].
However, `pdoc` supports docstrings attached to module (or global)
variables, class variables, and object instance variables; all in
the same way as proposed in [PEP-224], with a docstring following the
variable assignment.
For example:
[PEP-224]: http://www.python.org/dev/peps/pep-0224
module_variable = 1
"""Docstring for module_variable."""
class C:
class_variable = 2
"""Docstring for class_variable."""
def __init__(self):
self.variable = 3
"""Docstring for instance variable."""
While the resulting variables have no `__doc__` attribute,
`pdoc` compensates by reading the source code (when available)
and parsing the syntax tree.
By convention, variables defined in a class' `__init__` method
and attached to `self` are considered and documented as
_instance_ variables.
Class and instance variables can also [inherit docstrings][docstrings inheritance].

@csm10495
Copy link
Contributor Author

@kernc added documentation, fixed test. Please check again. Thanks.

@kernc
Copy link
Member

kernc commented Jan 2, 2021

Applied with slight modification.

This is a great feature. Many thanks @csm10495! ✨

@kernc kernc merged commit 49b7773 into pdoc3:master Jan 2, 2021
kernc pushed a commit to johann-petrak/pdoc that referenced this pull request Jun 22, 2024
…3#292)

* Add support for variable docstrings starting with '#:'

* Get tests passing on Windows

* Updates from the PRD

* Add some unit tests, lint

* Update pdoc/__init__.py

* PR fixes

* PR updates, add documentation

* Revert unrelated change

* Touch ups

* Reword docs
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

setup.py test doesn't seem to work Docstrings for variables from doc-comments above
2 participants