handsdown 0.1.4

# 🙌 Handsdown - Python documentation generator

🙌 Handsdown - Python documentation generator

Python docstring-based documentation generator for lazy perfectionists.

• 🙌 Handsdown - Python documentation generator
  • 🔬 Features
  • 🐏 Examples
  • 🎉 Usage
    • 💻 From command line
    • 🧩 As a module
  • 🐶 Installation
  • 🔧 Development

🔬 Features

• 👓 PEP257, Google and RST docstrings support. All of them are converted to a valid markdown.
• 🐍 Works with Django and Flask apps
• 🐈 Github-friendly. Use your local markdown viewer or open docs right on Github
• 📚 Signatures for every class, function and method.
• 🚀 Support for type annotations. Even for the ones from the __future__!
• 📦 Nice list of all modules in Modules
• 🔎 Gather all scattered README.md in submodules to one place
• 🚧 Links to source code from every doc section.
• #️⃣ Make links by just adding module.import.String to docs.
• 💕 Do you love type annotations? Well, you get auto-discovery of related modules for free!

🐏 Examples

handsdown built a nice documentation for itself to show it's abilities. Check how it works under the hood or discover examples with different docstrings format.

🎉 Usage

💻 From command line

Just go to your favorite project that has lots of docstrings but missing auto-generated docs and let handsdown do the thing.

cd ~/my/project

# output buolt MD files to docs/*
handsdown

# or provide custom output: output_dir/*
handsdown -o output_dir

# generate docs only for my_module, but no migrations, plz
handsdown my_module --exclude my_module/migrations

Navigate to docs/README.md to check your new documentation!

🧩 As a module

from handsdown import Generator, PathFinder

# this is our project root directory
repo_path = Path.cwd()

# this little tool works like `pathlib.Path.glob` with some extra magic
# but in this case `repo_path.glob("**/*.py")` would do as well
path_finder = PathFinder(repo_path, "**/*.py")

# no docs for tests and build
path_finder.exclude("tests/*", "build/*")

# initialize generator
handsdown = Generator(
    input_path=repo_path,
    output_path=repo_path / 'output',
    source_paths=path_finder.list()
)

# generate all docs at once
handsdown.generate_docs()

# or generate just for one doc
handsdown.generate_doc(repo_path / 'my_module' / 'source.py')

# and generate index.md file
handsdown.generate_index()

# navigate to `output` dir and check results

🐶 Installation

Install using pip

pip install handsdown

🔧 Development

• Install pipenv
• Run pipenv install -d
• Use black formatter in your IDE