Skip to main content

Socratic Docs

PyPI Downloads GitHub License

Automated documentation generation, code extraction, and project management for Python projects.

Overview

Socratic Docs provides a toolkit for generating, managing, and organizing project documentation. It automates the tedious process of creating documentation artifacts and managing project structure through git integration.

Features

Core Modules

  1. CodeExtractor - Extract and analyze source code

    • Parse Python modules and classes
    • Extract function signatures and docstrings
    • Generate code inventories
    • Support for package analysis
  2. DocumentationGenerator - Generate documentation

    • Auto-generate README.md with project overview
    • Create API reference documentation
    • Generate architecture documentation
    • Produce setup and installation guides
  3. MultiFileCodeSplitter - Split large codebases into organized files

    • Organize code by module/package
    • Generate file structure
    • Support for custom naming conventions
    • Preserve code relationships
  4. ProjectTemplateGenerator - Create project scaffolding

    • Generate boilerplate project structures
    • Create standardized layouts
    • Support multiple project types
    • Include configuration files
  5. ArtifactSaver - Save documentation and artifacts

    • Write files to disk
    • Organize by directory
    • Support multiple formats (markdown, text, code)
    • Create index files
  6. GitRepositoryManager - Manage git repositories

    • Initialize repositories
    • Add and commit files
    • Track documentation changes
    • Integrate with version control
  7. GitInitializer - Setup git for projects

    • Initialize new repositories
    • Configure git settings
    • Create initial commits
    • Setup .gitignore files

Installation

Basic Installation

pip install socratic-docs

With Optional Dependencies

# With git integration
pip install socratic-docs[all]

Quick Start

Example 1: Extract Code and Generate Documentation

from socratic_docs import CodeExtractor, DocumentationGenerator, ArtifactSaver

# Step 1: Extract code information
extractor = CodeExtractor()
code_info = extractor.extract_from_package("my_package")

# Step 2: Generate documentation
generator = DocumentationGenerator()
docs = generator.generate_all(code_info)
# docs contains README.md, API.md, ARCHITECTURE.md, SETUP.md

# Step 3: Save artifacts
saver = ArtifactSaver(output_dir="./docs_output")
saver.save_documents(docs)
saver.create_index()

Example 2: Generate Project Template

from socratic_docs import ProjectTemplateGenerator

generator = ProjectTemplateGenerator()

template = generator.generate_template(
    project_name="my_awesome_project",
    project_type="library",
    description="An awesome Python library",
    author="Your Name"
)

Example 3: Git Integration Workflow

from socratic_docs import (
    GitInitializer,
    CodeExtractor,
    DocumentationGenerator,
    GitRepositoryManager,
    ArtifactSaver
)

# Initialize a new git repository
git_init = GitInitializer(repo_path="./my_project")
git_init.initialize()

# Extract code and generate docs
extractor = CodeExtractor()
code_info = extractor.extract_from_package("my_package")

generator = DocumentationGenerator()
docs = generator.generate_all(code_info)

# Save and commit
saver = ArtifactSaver(output_dir="./my_project/docs")
saver.save_documents(docs)

git_mgr = GitRepositoryManager(repo_path="./my_project")
git_mgr.add_files("docs/")
git_mgr.commit("docs: Add auto-generated documentation")

Example 4: Split Large Codebase

from socratic_docs import MultiFileCodeSplitter

splitter = MultiFileCodeSplitter()

result = splitter.split_by_module(
    input_file="monolithic_app.py",
    output_dir="./modular_structure"
)

Use Cases

Documentation for Open Source Projects

  • Auto-generate README and API docs
  • Keep documentation in sync with code
  • Generate changelog and architecture guides
  • Create installation and setup guides

Internal Documentation

  • Document applications
  • Generate code inventories
  • Create architecture diagrams
  • Track project structure changes

Project Scaffolding

  • Quickly bootstrap new projects
  • Ensure consistent project structure
  • Auto-configure build tools
  • Generate config files

Documentation as Code

  • Version control documentation with code
  • Generate docs from code docstrings
  • Automate documentation updates
  • Integrate with CI/CD pipelines

Integration with Socratic Ecosystem

  • socratic-nexus: Use LLMs to improve documentation generation
  • socratic-analyzer: Analyze code quality and document findings
  • socratic-workflow: Integrate documentation generation into workflows
  • socratic-learning: Track improvements in documentation quality

Architecture

See ARCHITECTURE.md for detailed architecture documentation.

API Reference

See docs/API_REFERENCE.md for complete API documentation.

Examples

See the examples/ directory for complete, runnable examples:

  • 01_extract_and_generate.py - Extract code and generate documentation
  • 02_project_templates.py - Generate project scaffolding
  • 03_git_workflow.py - Git-based documentation workflow

Contributing

Contributions are welcome!

License

MIT License - see LICENSE for details.

Support


Origin

This package comes from the Socrates research prototype, which is not maintained as a product. Status: alpha. Written by Efthimios Angelopoulos with AI coding assistants (Claude Code); I design, review and test it. Contact: Hermes_creative@proton.me.

Use This Package Standalone:

pip install socratic-docs

Or As Part of Socrates Platform:

pip install socrates-ai  # Includes 37+ modules + all 11 packages

Integration Example:

See the Socrates ECOSYSTEM.md for detailed integration examples showing how to use socratic-docs with other Socratic packages.

Related packages you might use together:

More Information:


Metadata

Release files for socratic-docs 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for socratic-docs 0.2.2
File Size Uploaded Provenance Actions
socratic_docs-0.2.2.tar.gz 45.9 kB Without provenance Details for socratic_docs-0.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for socratic-docs 0.2.2
File Interpreter ABI Platform Actions
socratic_docs-0.2.2-py3-none-any.whl Python 3 none any Details for socratic_docs-0.2.2-py3-none-any.whl

Total release size: 94.5 kB

Release files / socratic_docs-0.2.2.tar.gz

Download URL socratic_docs-0.2.2.tar.gz
Size 45.9 kB
Tags Source
SHA-256 checksum
How to use checksums
895c1341959f96236f1d25c6652a7eb5989b46755a5e9d140b886c88d73b4918
BLAKE2b-256 checksum
How to use checksums
19ae0ef9f41d8acbf884eac09844a7dffb33866f873f4e75302a6e3c6645621c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via pyupload/1 (stdlib)

Release files / socratic_docs-0.2.2-py3-none-any.whl

Download URL socratic_docs-0.2.2-py3-none-any.whl
Size 48.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
44725bfdedf8fd1c7e536f3799ab44b46796672d2cecdcf0f1105fd62f8878e6
BLAKE2b-256 checksum
How to use checksums
7834186f9c2cfd18c5f8f1192b6678694396b40b5a73957d0e3ba5996a6a9750
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via pyupload/1 (stdlib)

Security for socratic-docs 0.2.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page