Metadata-Version: 2.1
Name: handsdown
Version: 0.1.5
Summary: # 🙌 Handsdown - Python documentation generator
Home-page: https://github.com/vemel/handsdown
Author: Vlad Emelianov
Author-email: vlad.emelianov.nz@gmail.com
License: UNKNOWN
Project-URL: Source, https://github.com/vemel/handsdown
Project-URL: Documentation, https://github.com/vemel/handsdown/tree/0.1.5/docs/handsdown_index.md#handsdown
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: Django
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown

# 🙌 Handsdown - Python documentation generator

![PyPI](https://img.shields.io/pypi/v/handsdown)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/handsdown)
![PyPI - Format](https://img.shields.io/pypi/format/handsdown)
![PyPI - Status](https://img.shields.io/pypi/status/handsdown)
![Travis (.org)](https://img.shields.io/travis/vemel/handsdown)
![Codecov](https://img.shields.io/codecov/c/github/vemel/handsdown)

Python docstring-based documentation generator for lazy perfectionists.

- [🙌 Handsdown - Python documentation generator](#%f0%9f%99%8c-handsdown---python-documentation-generator)
  - [🔬 Features](#%f0%9f%94%ac-features)
  - [🤔 Do you need handsdown?](#%f0%9f%a4%94-do-you-need-handsdown)
  - [🐏 Examples](#%f0%9f%90%8f-examples)
  - [🎉 Usage](#%f0%9f%8e%89-usage)
    - [💻 From command line](#%f0%9f%92%bb-from-command-line)
    - [📝 GitHub Pages](#%f0%9f%93%9d-github-pages)
    - [🧩 As a module](#%f0%9f%a7%a9-as-a-module)
  - [🐶 Installation](#%f0%9f%90%b6-installation)
  - [🔧 Development](#%f0%9f%94%a7-development)

## 🔬 Features

- 👓 [PEP 257](https://www.python.org/dev/peps/pep-0257/),
  [Google](http://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
  and [reStructuredText](https://www.python.org/dev/peps/pep-0287/)
  docstrings support. All of them are converted to a valid markdown.
- 🐍 Works with [Django](https://www.djangoproject.com/) and [Flask](https://palletsprojects.com/p/flask/) apps
- 🐈 GitHub-friendly. Use your local markdown viewer, open docs
  [right on GitHub](https://github.com/vemel/handsdown/blob/master/docs/README.md) or deploy it on
  [GitHub Pages](https://vemel.github.io/handsdown/)!
- 📚 Signatures for every class, function, property and method.
- 🚀 Support for type annotations. Even for the ones from the `__future__`!
- 📦 Nice list of all modules in [Modules](https://github.com/vemel/handsdown/blob/master/docs/README.md)
- 🔎 Gather all scattered `README.md` in submodules to one place
- 🚧 Find related source code from every doc section.
- #️⃣ Make links by just adding `module.import.String` to docs.
- 💕 Do you use type annotations? Well, you get auto-discovery of related modules for free!

## 🤔 Do you need handsdown?

You definitely *do* if you:

- prefer to automate documentation builds
- work with a team and plan to simplify knowledge sharing
- want to show your project without navigating through a source code
- build `Django` or `Flask` applications, and even if you do not
- are proud of your project and are not afraid to show it
- love Open Source

And probably *do not* if you:

- plan to build html pages locally (Look at
- [pydocmd](https://pypi.org/project/pydoc-markdown/), they are doing a great job!)
- not very into docstrings and type annotations
- like to abstract a documentation away from the way things really are
- use [Pandas docstrings](https://pandas.pydata.org/pandas-docs/stable/development/contributing_docstring.html)
  as they are not supported yet

## 🐏 Examples

`handsdown` built a nice
[documentation](https://github.com/vemel/handsdown/blob/master/docs/README.md) for
itself to show it's abilities. Check how it works under the hood or discover
[examples](https://github.com/vemel/handsdown/blob/master/docs/examples_index.md)
with different docstrings format.

## 🎉 Usage

### 💻 From command line

Just go to your favorite project that has lots of docstrings but missing
auto-generated docs, install dependencies to avoid import errors and let
`handsdown` do the thing.

```bash
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

# okay, what about Django?
# you need to set `DJANGO_SETTINGS_MODULE`
# and exclude migrations folders as they usually are not very interesting
export DJANGO_SETTINGS_MODULE="settings" # use your path to settings
handsdown --exclude */migrations
```

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

### 📝 GitHub Pages

`handsdown` comes with built-in support for [GitHub Pages](https://pages.github.com/),
although some setup is required. By default documentation uses relative links to source files,
so for `GitHub Pages` we need absolute URLs to a GitHub repositore for `find in source code`
links to work.

Now let's generate `GitHub Pages`-friendly documentation

```bash
# Generate documentation that points to master branch
# do not use custom output location, as as `GitHub Pages`
# works only with `docs` directory
handsdown --gh-pages `git config --get remote.origin.url`

# or specify GitHub url directly
handsdown --gh-pages https://github.com/<user>/<project>/blob/master/
```

Commit your changes and enable `GitHub Pages` by setting your project
`Settings` > `GitHub Pages` > `Source` to `master branch /docs folder`

That's it, you are good to go! Add plugins to `docs/_config.yml` or change
theme to add your own touch.

If you still want to have relative links to source, e.g. for using docs locally,
generate docs to another folder

```bash
handsdown -o docs_local # `docs_local` folder will be created in your project root
```

### 🧩 As a module

```python
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.glob("**/*.py")
)

# 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

```bash
pip install handsdown
```

## 🔧 Development

- Install [pipenv](https://pypi.org/project/pipenv/)
- Run `pipenv install -d`
- Use `black` formatter in your IDE


