Metadata-Version: 2.1
Name: handsdown
Version: 0.2.2
Summary: Python docstring-based documentation generator for lazy perfectionists.
Home-page: https://vemel.github.io/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://vemel.github.io/handsdown/
Description: # 🙌 Handsdown - Python documentation generator
        
        ![PyPI](https://img.shields.io/pypi/v/handsdown)
        ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/handsdown)
        ![PyPI - Wheel](https://img.shields.io/pypi/wheel/handsdown)
        ![Travis (.org)](https://img.shields.io/travis/vemel/handsdown)
        ![Read the Docs](https://img.shields.io/readthedocs/handsdown)
        ![Codecov](https://img.shields.io/codecov/c/github/vemel/handsdown)
        
        Python docstring-based documentation generator for lazy perfectionists.
        
        
        ## 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
        - Can be used locally, or
          [right on GitHub](https://github.com/vemel/handsdown/blob/master/docs/README.md) or even deployed on
          [GitHub Pages](https://vemel.github.io/handsdown/) and [Read the Docs](https://handsdown.readthedocs.io/)!
        - 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/MODULES.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 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://vemel.github.io/handsdown/#-handsdown---python-documentation-generator) for
        itself to show it's abilities. Check how it works under the hood or discover
        [examples](https://vemel.github.io/handsdown/examples/#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, 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!
        
        ### 📝 As a GitHub Pages manager
        
        With `--external` CLI flag, `handsdown` generates all required configuration
        for [GitHub Pages](https://pages.github.com/), so you just need to setup your
        GitHub repository.
        
        ```bash
        # Generate documentation that points to master branch
        # do not use custom output location, as `GitHub Pages`
        # works only with `docs` directory
        handsdown --external `git config --get remote.origin.url`
        
        # or specify GitHub url directly
        handsdown --external https://github.com/<user>/<project>/blob/master/
        ```
        
        - Generate documentation with `--external` flag as shown above, do not use `--output`
          flag, only `docs` folder is supported by `GitHub Pages`
        - Commit and push all changes a to `master` branch.
        - Set your GitHub project `Settings` > `GitHub Pages` > `Source` to `master branch /docs folder`
        
        All set! You can change `docs/_config.yml` to add your own touch.
        
        With `--external` flag links to your source are absolute and point to your GitHub repo. If you
        still want to have relative links to source, e.g. for using docs locally,
        generate docs to another folder
        
        ```bash
        # `docs_local` folder will be created in your project root
        # you probably want to add it to .gitignore
        handsdown -o docs_local
        ```
        
        ### 🐏 Deploy on Read the Docs
        
        With `--external` CLI flag, `handsdown` generates all required configuration
        for [Read the Docs](https://readthedocs.org/), so you just need to to add your
        GitHub repository to `Read the Docs`.
        
        ```bash
        # Generate documentation that points to master branch
        # do not use custom output location, as `GitHub Pages`
        # works only with `docs` directory
        handsdown --external `git config --get remote.origin.url`
        
        # or specify GitHub url directly
        handsdown --external https://github.com/<user>/<project>/blob/master/
        ```
        
        - Generate documentation with `--external` flag as shown above, do not use `--output`
          flag, only `docs` folder is supported by `Read the Docs`
        - Commit and push all changes a to `master` branch.
        - Add your repository on [Read the Docs](https://readthedocs.org/)
        
        All set! You can change `.readthedocs.yml` and `mkdocs.yml` to add your own touch.
        
        ### 📋 Build static HTML
        
        ```bash
        # Generate documentation that points to master branch
        # with source links pointing to your repository
        # this command also creates `mkdocs.yml`
        handsdown --external `git config --get remote.origin.url`
        
        # Run mkdocs to build HTML
        mkdocs build
        ```
        
        ### 🧩 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` from PyPI
        
        ```bash
        pip install handsdown
        ```
        
        or directly from GitHub if you cannot wait to test new features
        
        ```bash
        pip install git+https://github.com/vemel/handsdown.git
        ```
        
        ## Development
        
        - Install [pipenv](https://pypi.org/project/pipenv/)
        - Run `pipenv install -d`
        - Use `black` formatter in your IDE
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: Django
Classifier: Framework :: Django :: 1.8
Classifier: Framework :: Django :: 1.9
Classifier: Framework :: Django :: 2.0
Classifier: Framework :: Django :: 2.1
Classifier: Framework :: Django :: 2.2
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Documentation
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Description-Content-Type: text/markdown
