Metadata-Version: 2.1
Name: gh2md
Version: 0.2
Summary: Export Github repository issues to markdown files: https://github.com/mattduck/gh2md.
Home-page: https://github.com/mattduck/gh2md
Author: Matthew Duck
Author-email: matt@mattduck.com
Maintainer: Matthew Duck
Maintainer-email: matt@mattduck.com
License: MIT
Keywords: github,issues,markdown
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: six
Requires-Dist: PyGithub (~=1.34)
Requires-Dist: retrying (==1.3.3)

gh2md
=====

|PyPI|  |Travis|

Dump issues for a Github repository into a single, readable markdown file.

There are various other projects that handle Github issue exports
(Eg. `offline-issues <https://github.com/jlord/offline-issues>`_), but I couldn't
find one that writes all issues, comments and metadata to a single readable
file.


Example exports
---------------

An example exported file is included in the `examples directory <examples/sshrc.md>`_.

Default behaviour is to export all issues and open PRs. Closed PRs are ignored.


Github workflow: backup issues as a markdown file in your repo
--------------------------------------------------------------

`@0ut0fcontrol <https://github.com/0ut0fcontrol>`_ contributed a github workflow
that uses `gh2md` to run a nightly export to `issues.md`, and push it back to
your repo. You can find the thread and workflow code `here
<https://github.com/mattduck/gh2md/issues/11>`_.

This has been added to the `gh2md` repo itself, so you can see an up-to-date
export in `issues.md <./issues.md>`_.


Usage
-----

Run export for ``pope/ob-go``, prompting for login to ``mygithubuser``::

    gh2md pope/ob-go ob-go.md --login mygithubuser


Run export for ``sarabander/sicp``, passing in token::

    gh2md sarabander/sicp sicp.md --token myAPItoken


Run export for ``paulirish/git-open``, pulling token from environment::

    export GITHUB_ACCESS_TOKEN=myAPItoken
    gh2md paulirish/git-open git-open.md


Run export for ``shezadkhan137/required``, pulling token from file::

    echo myAPItoken > ~/.github-token
    gh2md shezadkhan137/required required.md


Full help::

    $ gh2md -h
    usage: gh2md [-h] [-l LOGIN_USER] [-t TOKEN] repo outpath

    Export Github repository issues and comments into a single
    markdown file. https://github.com/mattduck/gh2md.

    Credentials are resolved in the following order:

    - The --login flag always takes precedence and will prompt for this user.
    - The --token flag.
    - A `GITHUB_ACCESS_TOKEN` environment variable.
    - An API token stored in `~/.github-token`.

    positional arguments:
    repo                  Github repo to export, in format "owner/repo_name".
    outpath               Path to write exported issues.

    optional arguments:
    -h, --help            show this help message and exit
    -l LOGIN_USER, --login LOGIN_USER
                            Prompt to login as this Github user. If provided, this
                            takes precedence over any token found in the
                            environment. If not provided and no token is found,
                            you will be prompted to login as the repository owner.
    -t TOKEN, --token TOKEN
                            Automatically login with this Github API token. If
                            --login is provided, this is ignored.


Install
-------

``pip install gh2md``. Alternatively, clone the repository and run ``make install``.


TODO
-----

- Improve performance. Currently fetching issues using PyGithub is slow - I
  assume it's possible to bulk-fetch most of the data.

- Add flag to toggle inclusion of images.

- Add arg(s) to control which data is exported - open/closed, issues/PRs.

- Support 2FA login - currently if 2FA is enabled on your account you must setup
  an access token.

.. |PyPI| image:: https://img.shields.io/pypi/v/gh2md.svg
   :target: https://pypi.python.org/pypi/gh2md

.. |Travis| image:: https://travis-ci.org/mattduck/gh2md.svg?branch=master
   :target: https://travis-ci.org/mattduck/gh2md


