great-docs 0.1.0__tar.gz

great_docs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Posit Software, PBC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

great_docs-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+recursive-include great_docs/assets *
+include great_docs/assets/.gitignore

great_docs-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: great-docs
+Version: 0.1.0
+Summary: An easy-to-use documentation site generator for Python packages
+Author-email: Rich Iannone <riannone@me.com>
+Maintainer-email: Rich Iannone <riannone@me.com>
+License: MIT License
+        
+        Copyright (c) 2026 Posit Software, PBC
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/posit-dev/great-docs
+Project-URL: Repository, https://github.com/posit-dev/great-docs
+Project-URL: Documentation, https://posit-dev.github.io/great-docs/
+Project-URL: Bug Tracker, https://github.com/posit-dev/great-docs/issues
+Keywords: documentation,documentation-generator,api-documentation,quarto,python
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jupyter>=1.1.1
+Requires-Dist: py-yaml12>=0.1.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: griffe<2.0.0,>=0.35.0
+Requires-Dist: pygments>=2.0.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: pyspellchecker>=0.7.0
+Requires-Dist: tabulate>=0.9.0
+Requires-Dist: Pillow>=9.0.0
+Requires-Dist: cairosvg>=2.5.0
+Requires-Dist: ruff>=0.9.9
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=3.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.5; extra == "dev"
+Requires-Dist: ruff>=0.9.9; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pyright>=1.1.407; extra == "dev"
+Requires-Dist: build>=0.7; extra == "dev"
+Requires-Dist: twine>=3.4; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: jupyter>=1.0.0; extra == "docs"
+Dynamic: license-file
+
+# Great Docs
+
+[![Python versions](https://img.shields.io/pypi/pyversions/great-docs.svg)](https://pypi.org/project/great-docs/)
+[![PyPI](https://img.shields.io/pypi/v/great-docs?logo=python&logoColor=white&color=orange)](https://pypi.org/project/great-docs/)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/great-docs)](https://pypistats.org/packages/great-docs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://choosealicense.com/licenses/mit/)
+[![CI Build](https://github.com/posit-dev/great-docs/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/posit-dev/great-docs/actions/workflows/test.yml)
+[![Repo Status](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.1%20adopted-ff69b4.svg)](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html)
+
+Great Docs automatically creates professional documentation with auto-generated API references, CLI documentation, smart navigation, and modern styling.
+
+## Features
+
+- **One-command setup** — `great-docs init` creates your entire docs site
+- **Auto-generated API docs** — discovers and documents your package's public API
+- **Docstring detection** — automatically detects NumPy, Google, or Sphinx style
+- **CLI documentation** — generates reference pages for Click-based CLIs
+- **Smart organization** — intelligent class/method/function categorization
+- **User Guide support** — write narrative documentation alongside API reference
+- **Source links** — automatic links to source code on GitHub
+- **LLM-friendly** — auto-generates `llms.txt` and `llms-full.txt` for AI documentation indexing
+- **GitHub Pages ready** — one command sets up deployment workflow
+
+## Quick Start
+
+### Install
+
+Great Docs is not yet available on PyPI, so, install from GitHub:
+
+```bash
+pip install git+https://github.com/posit-dev/great-docs.git
+```
+
+### Initialize
+
+Navigate to your Python project and run:
+
+```bash
+great-docs init
+```
+
+This auto-detects your package and creates a `great-docs.yml` configuration file with your API structure.
+
+### Build
+
+```bash
+great-docs build
+```
+
+This creates the `great-docs/` directory with all assets and builds your site to `great-docs/_site/`.
+
+### Preview
+
+```bash
+great-docs preview
+```
+
+Opens the built site in your browser.
+
+### Deploy
+
+```bash
+great-docs setup-github-pages
+```
+
+Creates a GitHub Actions workflow for automatic deployment.
+
+## What You Get
+
+- **Landing page** from your README with a metadata sidebar (authors, license, links)
+- **API reference** with classes, functions, and methods organized and styled
+- **CLI reference** with `--help` output in terminal style
+- **User Guide** from your `user_guide/` directory
+- **Source links** to GitHub for every documented item
+- **Mobile-friendly** responsive design
+
+## Documentation
+
+The User Guide covers:
+
+- [Installation](https://posit-dev.github.io/great-docs/user-guide/installation.html)
+- [Quick Start](https://posit-dev.github.io/great-docs/user-guide/quickstart.html)
+- [Configuration](https://posit-dev.github.io/great-docs/user-guide/configuration.html)
+- [Theming & Appearance](https://posit-dev.github.io/great-docs/user-guide/theming.html)
+- [Cross-Referencing](https://posit-dev.github.io/great-docs/user-guide/cross-referencing.html)
+- [API Documentation](https://posit-dev.github.io/great-docs/user-guide/api-documentation.html)
+- [CLI Documentation](https://posit-dev.github.io/great-docs/user-guide/cli-documentation.html)
+- [User Guides](https://posit-dev.github.io/great-docs/user-guide/user-guides.html)
+- [Custom Sections](https://posit-dev.github.io/great-docs/user-guide/custom-sections.html)
+- [Blog](https://posit-dev.github.io/great-docs/user-guide/blog.html)
+- [Building & Previewing](https://posit-dev.github.io/great-docs/user-guide/building.html)
+- [Deployment](https://posit-dev.github.io/great-docs/user-guide/deployment.html)
+- [Link Checker](https://posit-dev.github.io/great-docs/user-guide/link-checker.html)
+- [Spell Checking](https://posit-dev.github.io/great-docs/user-guide/spell-checker.html)
+- [Changelog](https://posit-dev.github.io/great-docs/user-guide/changelog.html)
+
+## License
+
+MIT License. See [LICENSE](https://posit-dev.github.io/great-docs/license.html) for details.

great_docs-0.1.0/README.md

@@ -0,0 +1,100 @@
+# Great Docs
+
+[![Python versions](https://img.shields.io/pypi/pyversions/great-docs.svg)](https://pypi.org/project/great-docs/)
+[![PyPI](https://img.shields.io/pypi/v/great-docs?logo=python&logoColor=white&color=orange)](https://pypi.org/project/great-docs/)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/great-docs)](https://pypistats.org/packages/great-docs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://choosealicense.com/licenses/mit/)
+[![CI Build](https://github.com/posit-dev/great-docs/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/posit-dev/great-docs/actions/workflows/test.yml)
+[![Repo Status](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.1%20adopted-ff69b4.svg)](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html)
+
+Great Docs automatically creates professional documentation with auto-generated API references, CLI documentation, smart navigation, and modern styling.
+
+## Features
+
+- **One-command setup** — `great-docs init` creates your entire docs site
+- **Auto-generated API docs** — discovers and documents your package's public API
+- **Docstring detection** — automatically detects NumPy, Google, or Sphinx style
+- **CLI documentation** — generates reference pages for Click-based CLIs
+- **Smart organization** — intelligent class/method/function categorization
+- **User Guide support** — write narrative documentation alongside API reference
+- **Source links** — automatic links to source code on GitHub
+- **LLM-friendly** — auto-generates `llms.txt` and `llms-full.txt` for AI documentation indexing
+- **GitHub Pages ready** — one command sets up deployment workflow
+
+## Quick Start
+
+### Install
+
+Great Docs is not yet available on PyPI, so, install from GitHub:
+
+```bash
+pip install git+https://github.com/posit-dev/great-docs.git
+```
+
+### Initialize
+
+Navigate to your Python project and run:
+
+```bash
+great-docs init
+```
+
+This auto-detects your package and creates a `great-docs.yml` configuration file with your API structure.
+
+### Build
+
+```bash
+great-docs build
+```
+
+This creates the `great-docs/` directory with all assets and builds your site to `great-docs/_site/`.
+
+### Preview
+
+```bash
+great-docs preview
+```
+
+Opens the built site in your browser.
+
+### Deploy
+
+```bash
+great-docs setup-github-pages
+```
+
+Creates a GitHub Actions workflow for automatic deployment.
+
+## What You Get
+
+- **Landing page** from your README with a metadata sidebar (authors, license, links)
+- **API reference** with classes, functions, and methods organized and styled
+- **CLI reference** with `--help` output in terminal style
+- **User Guide** from your `user_guide/` directory
+- **Source links** to GitHub for every documented item
+- **Mobile-friendly** responsive design
+
+## Documentation
+
+The User Guide covers:
+
+- [Installation](https://posit-dev.github.io/great-docs/user-guide/installation.html)
+- [Quick Start](https://posit-dev.github.io/great-docs/user-guide/quickstart.html)
+- [Configuration](https://posit-dev.github.io/great-docs/user-guide/configuration.html)
+- [Theming & Appearance](https://posit-dev.github.io/great-docs/user-guide/theming.html)
+- [Cross-Referencing](https://posit-dev.github.io/great-docs/user-guide/cross-referencing.html)
+- [API Documentation](https://posit-dev.github.io/great-docs/user-guide/api-documentation.html)
+- [CLI Documentation](https://posit-dev.github.io/great-docs/user-guide/cli-documentation.html)
+- [User Guides](https://posit-dev.github.io/great-docs/user-guide/user-guides.html)
+- [Custom Sections](https://posit-dev.github.io/great-docs/user-guide/custom-sections.html)
+- [Blog](https://posit-dev.github.io/great-docs/user-guide/blog.html)
+- [Building & Previewing](https://posit-dev.github.io/great-docs/user-guide/building.html)
+- [Deployment](https://posit-dev.github.io/great-docs/user-guide/deployment.html)
+- [Link Checker](https://posit-dev.github.io/great-docs/user-guide/link-checker.html)
+- [Spell Checking](https://posit-dev.github.io/great-docs/user-guide/spell-checker.html)
+- [Changelog](https://posit-dev.github.io/great-docs/user-guide/changelog.html)
+
+## License
+
+MIT License. See [LICENSE](https://posit-dev.github.io/great-docs/license.html) for details.

great_docs-0.1.0/great_docs/__init__.py

@@ -0,0 +1,21 @@
+try:
+    from importlib.metadata import PackageNotFoundError, version
+except ImportError:  # pragma: no cover
+    from importlib_metadata import PackageNotFoundError, version  # type: ignore[import-not-found]
+
+try:  # pragma: no cover
+    __version__ = version("great-docs")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"
+
+from .cli import main
+from .config import Config, create_default_config, load_config
+from .core import GreatDocs
+
+__all__ = [
+    "Config",
+    "GreatDocs",
+    "create_default_config",
+    "load_config",
+    "main",
+]

great_docs-0.1.0/great_docs/_directives.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+
+@dataclass
+class DocDirectives:
+    """
+    Extracted directives from a docstring.
+
+    Attributes
+    ----------
+    seealso
+        List of `(name, description)` tuples for cross-referencing. The description is an empty
+        string when not provided.
+    nodoc
+        If `True`, exclude this item from documentation.
+    """
+
+    seealso: list[tuple[str, str]] = field(default_factory=list)
+    nodoc: bool = False
+
+    def __bool__(self) -> bool:
+        """Return True if any directive was found."""
+        return bool(self.seealso or self.nodoc)
+
+
+# Single-line directive patterns (with % prefix, no colon)
+# Each pattern matches a complete line starting with the directive
+DIRECTIVE_PATTERNS = {
+    "seealso": re.compile(r"^\s*%seealso\s+(.+?)\s*$", re.MULTILINE),
+    "nodoc": re.compile(r"^\s*%nodoc(?:\s+(true|yes|1))?\s*$", re.MULTILINE | re.IGNORECASE),
+}
+
+# Combined pattern for stripping all directives (matches the whole line including newline)
+ALL_DIRECTIVES_PATTERN = re.compile(
+    r"^\s*%(?:seealso|nodoc)(?:\s+.*)?$\n?", re.MULTILINE | re.IGNORECASE
+)
+
+
+def extract_directives(docstring: str | None) -> DocDirectives:
+    """
+    Extract Great Docs directives from a docstring.
+
+    Parameters
+    ----------
+    docstring
+        The docstring to parse. Can be None.
+
+    Returns
+    -------
+    DocDirectives
+        A dataclass containing extracted directive values.
+
+    Examples
+    --------
+    >>> doc = '''
+    ... Short description.
+    ...
+    ... %seealso func_a, func_b
+    ...
+    ... Parameters
+    ... ----------
+    ... x : int
+    ... '''
+    >>> directives = extract_directives(doc)
+    >>> directives.seealso
+    [('func_a', ''), ('func_b', '')]
+    """
+    directives = DocDirectives()
+
+    if not docstring:
+        return directives
+
+    # Extract %seealso (comma-separated list, each entry may have ": description")
+    if match := DIRECTIVE_PATTERNS["seealso"].search(docstring):
+        items: list[tuple[str, str]] = []
+        for entry in match.group(1).split(","):
+            entry = entry.strip()
+            if not entry:
+                continue
+            # Split on first " : " or ": " to get name and optional description
+            parts = re.split(r"\s*:\s*", entry, maxsplit=1)
+            name = parts[0].strip()
+            desc = parts[1].strip() if len(parts) > 1 else ""
+            if name:
+                items.append((name, desc))
+        directives.seealso = items
+
+    # Extract %nodoc
+    if DIRECTIVE_PATTERNS["nodoc"].search(docstring):
+        directives.nodoc = True
+
+    return directives
+
+
+def strip_directives(docstring: str | None) -> str:
+    """
+    Remove all Great Docs directives from a docstring.
+
+    This produces a clean docstring for rendering in documentation,
+    while the original docstring with directives remains in source
+    code for IDE display.
+
+    Parameters
+    ----------
+    docstring
+        The docstring to clean. Can be None.
+
+    Returns
+    -------
+    str
+        The docstring with all %directive lines removed.
+
+    Examples
+    --------
+    >>> doc = '''
+    ... Short description.
+    ...
+    ... %seealso func_a
+    ...
+    ... Parameters
+    ... ----------
+    ... x : int
+    ... '''
+    >>> print(strip_directives(doc))
+    Short description.
+    <BLANKLINE>
+    Parameters
+    ----------
+    x : int
+    """
+    if not docstring:
+        return docstring or ""
+
+    # Remove all directive lines
+    cleaned = ALL_DIRECTIVES_PATTERN.sub("", docstring)
+
+    # Clean up resulting multiple blank lines (more than 2 newlines -> 2 newlines)
+    cleaned = re.sub(r"\n{3,}", "\n\n", cleaned)
+
+    # Strip leading/trailing whitespace but preserve internal structure
+    return cleaned.strip()
+
+
+def has_directives(docstring: str | None) -> bool:
+    """
+    Check if a docstring contains any Great Docs directives.
+
+    Parameters
+    ----------
+    docstring
+        The docstring to check.
+
+    Returns
+    -------
+    bool
+        True if any %directive pattern is found.
+    """
+    if not docstring:
+        return False
+
+    return bool(ALL_DIRECTIVES_PATTERN.search(docstring))

great_docs-0.1.0/great_docs/_qrenderer/__init__.py

@@ -0,0 +1,53 @@
+from ._md_renderer import MdRenderer
+from ._render.api_page import RenderAPIPage
+from ._render.doc import RenderDoc
+from ._render.docattribute import RenderDocAttribute
+from ._render.docclass import RenderDocClass
+from ._render.docfunction import RenderDocFunction
+from ._render.docmodule import RenderDocModule
+from ._render.extending import (
+    exclude_attributes,
+    exclude_classes,
+    exclude_functions,
+    exclude_parameters,
+)
+from ._render.mixin_call import RenderDocCallMixin
+from ._render.mixin_members import RenderDocMembersMixin
+from ._render.reference_page import RenderReferencePage
+from ._render.reference_section import RenderReferenceSection
+from ._renderer import Renderer
+from .blueprint import blueprint, collect, strip_package_name
+
+# Re-exports from consolidated _renderer module
+from .introspection import Builder, get_object
+from .inventory import convert_inventory, create_inventory
+from .layout import Auto, Layout
+
+__all__ = (
+    "Renderer",
+    "RenderDoc",
+    "RenderDocClass",
+    "RenderDocFunction",
+    "RenderDocAttribute",
+    "RenderDocModule",
+    "RenderDocCallMixin",
+    "RenderDocMembersMixin",
+    "RenderReferencePage",
+    "RenderAPIPage",
+    "RenderReferenceSection",
+    "exclude_attributes",
+    "exclude_classes",
+    "exclude_functions",
+    "exclude_parameters",
+    # Consolidated from _renderer
+    "get_object",
+    "Builder",
+    "blueprint",
+    "strip_package_name",
+    "collect",
+    "MdRenderer",
+    "create_inventory",
+    "convert_inventory",
+    "Auto",
+    "Layout",
+)