Metadata-Version: 2.4
Name: docsource
Version: 0.1.0
Summary: Parse, check and update doc-string documentation
Author-email: Levente Hunyadi <hunyadi@gmail.com>
Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/hunyadi/docsource
Project-URL: Source, https://github.com/hunyadi/docsource
Keywords: docstring-documentation,docstring-checker,python-typing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Documentation
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.3; extra == "dev"
Requires-Dist: mypy>=1.18; extra == "dev"
Requires-Dist: ruff>=0.14; extra == "dev"
Dynamic: license-file

# docsource: Parse, check and update doc-string documentation

*docsource* parses Python documentation strings (a.k.a. *doc-string*) for (data) classes and functions.

A doc-string is broken down into the following components:

* A short description, which is the first block of text in the documentation string, and ends with a double newline or a parameter block.
* A long description, which is the optional block of text following the short description, and ends with a parameter block.
* A parameter block of named parameter and description string pairs in ReST-style, each declared with `param`.
* A `returns` declaration, which adds explanation to the return value.
* A `raises` declaration, which adds explanation to the exception type raised by the function on error.

```py
class SampleClass:
    def instance_method(self, a: str, b: int | None) -> str:
        """
        Short description of an instance method.

        :param a: Short description for `a`.
        :param b: Short description for `b`.
        :returns: A return value.
        :raise TypeError: A type exception rarely raised.
        :raise ValueError: A value exception rarely raised.
        :raise CustomException: A custom exception.
        """
        return ""
```

When the doc-string is attached to a data class, it is understood as the documentation string of the class `__init__` method.

## Compliance

*docsource* verifies if

* parameters listed in the function doc-string have corresponding parameters in the function signature,
* parameters declared in a function signature have corresponding doc-string entries (strict mode only),
* data-class members listed in the function doc-string have corresponding member variables in the data-class definition,
* members declared in a data-class have corresponding doc-string entries (strict mode only).

## Enumerations

Python's own doc-string mechanism doesn't allow attaching a description to enumeration members. However, documentation toolchains such as Sphinx's `autodoc` support this with a string literal immediately following the enumeration member value assignment:

```py
@enum.unique
class EnumType(enum.Enum):
    ENABLED = "enabled"
    "Documents the enumeration member `ENABLED`."

    DISABLED = "disabled"
    "Documents the enumeration member `DISABLED`."
```

*docsource* can parse source code with Python's `ast` module to extract these description text strings.

## Documentation style

*docsource* can normalize code documentation by reading source code (with Python's `ast`), identifying doc-string literals, parsing doc-string text, and producing a standardized doc-string with short description, and ReST-style parameter, return value and exception declarations.

## Refer to the source

* The function `parse_type` parses a ReST-style doc-string attached to a class or function into doc-string components, encapsulated in the class `Docstring`.
* The function `parse_text` parses raw doc-string text into its components.
* `check_docstring` verifies data-class and function doc-string text.
* `enum_labels` extracts textual description for enumeration members.
* `update_docstring` standardizes doc-string literals in Python source code.
